home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / max301c.zip / max.doc < prev    next >
Text File  |  1995-12-30  |  1MB  |  27,312 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                                              Maximus System
  7.                                                           Operations Manual
  8.  
  9.  
  10.                                                                 Version 3.0
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.                                                          Lanius Corporation
  59.  
  60.  
  61.  
  62.  
  63.  
  64.              Lanius Corporation, Kingston, Ontario, Canada
  65.              Copyright (c) 1989, 1995 by Lanius Corporation. All rights
  66.              reserved.
  67.  
  68.              No part of this work may be reproduced or transmitted in any
  69.              form or by any means, electronic or mechanical, including
  70.              photocopying and recording, or by any information storage or
  71.              retrieval system without the prior written permission of
  72.              Lanius Corporation.
  73.  
  74.              Maximus and Squish are trademarks of Lanius Corporation.
  75.  
  76.              MS-DOS, Windows, Windows 95 and Windows NT are trademarks of
  77.              Microsoft Corporation.
  78.  
  79.              IBM, PC-DOS and OS/2 are trademarks of International Business
  80.              Machines Corporation.
  81.  
  82.              Hayes is a trademark of Hayes Microcomputer Products, Inc.
  83.  
  84.              V.FC is a trademark of Rockwell International.
  85.  
  86.              MD5 is a trademark of RSA Data Security, Inc.
  87.  
  88.              BNU is a trademark of Unique Computing Pty Ltd.
  89.  
  90.              X00 and SIO are trademarks of Raymond L. Gwinn.
  91.  
  92.              All other trade names are trademarks of their respective
  93.              holders.
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.                                                                    Contents
  103.  
  104.  
  105.              1. Introduction ............................................1
  106.                 1.1. About Maximus.......................................1
  107.                 1.2. System Requirements.................................2
  108.                 1.3. Typographical Conventions...........................3
  109.                 1.4. Ordering a Printed Version of this Manual...........4
  110.                 1.5. Ordering Maximus for Commercial Use.................4
  111.  
  112.              2. Maximus Overview ........................................5
  113.                 2.1. Waiting for Callers.................................5
  114.                 2.2. Logging On..........................................5
  115.                 2.3. Command Stacking....................................6
  116.                 2.4. Guest Accounts......................................7
  117.                 2.5. The Main Menu.......................................7
  118.                 2.6. The Message Section.................................9
  119.                 2.7. The File Menu......................................21
  120.                 2.8. The Change Setup Menu..............................25
  121.                 2.9. The SysOp Menu.....................................28
  122.                 2.10. The Chat Menu.....................................28
  123.                 2.11. The Off-Line Reader Menu..........................29
  124.  
  125.              3. Installation ...........................................31
  126.                 3.1. Step 1: Unpacking the Distribution Files...........31
  127.                 3.2. Step 2: Running the Installation Program...........32
  128.                 3.3. Step 3: Configuring your Modem.....................33
  129.                 3.4. Step 4: Installing Communications Drivers..........34
  130.                 3.5. Step 5: Editing Configuration Files................37
  131.                 3.6. Step 6: About Control Files........................39
  132.                 3.7. Step 7: Compiling the Control Files................40
  133.                 3.8. Step 8: Starting Maximus...........................40
  134.                 3.9. Step 9: Support for Remote Callers.................42
  135.                 3.10. Step 10: Miscellaneous Information................51
  136.  
  137.              4. Customization ..........................................53
  138.                 4.1. Events and Yelling.................................53
  139.                 4.2. Access Control: Classes, Privilege Levels and Locks55
  140.                 4.3. Display Files: *.mec and *.bbs.....................62
  141.                 4.4. Message Areas and File Areas.......................64
  142.                 4.5. Maintaining File Areas.............................70
  143.                 4.6. Barricades and Extended Barricade Files............77
  144.                 4.7. Menus..............................................79
  145.                 4.8. QWK Mail Packing...................................81
  146.                 4.9. Multilingual Support...............................82
  147.  
  148.              5. Maximus Subsystems .....................................85
  149.                 5.1. Waiting for Callers Subsystem......................85
  150.                 5.2. Local File Attaches................................86
  151.                 5.3. QWK Mail Packer....................................88
  152.  
  153.  
  154.  
  155.              Contents                                                   iv
  156.  
  157.                 5.4. RIPscrip Support...................................92
  158.                 5.5. User Expiration and Subscriptions..................94
  159.                 5.6. Message Tracking System............................95
  160.  
  161.              6. External Programs .....................................105
  162.                 6.1. Execution Methods.................................105
  163.                 6.2. Swapping..........................................106
  164.                 6.3. Errorlevel Batch Files............................106
  165.                 6.4. Restarting After Errorlevel Exit..................107
  166.                 6.5. External Program Translation Characters...........109
  167.                 6.6. Running Doors.....................................112
  168.                 6.7. On-Line User Record Modification..................114
  169.                 6.8. Doors and OS/2....................................115
  170.  
  171.              7. Multinode Operations ..................................117
  172.                 7.1. Installation......................................118
  173.                 7.2. Multinode Chat Operation..........................121
  174.                 7.3. Master Control Program............................123
  175.  
  176.              8. Utility Documentation .................................125
  177.                 8.1. ACCEM: MECCA Decompiler...........................125
  178.                 8.2. ANS2BBS/MEC: ANSI to MEC conversion...............126
  179.                 8.3. CVTUSR: User File Conversions.....................127
  180.                 8.4. EDITCAL: Call Modification Utility................128
  181.                 8.5. FB: File Database Compiler........................129
  182.                 8.6. MAID: Language File Compiler......................132
  183.                 8.7. MAXPIPE: OS/2 Redirection Utility.................134
  184.                 8.8. MECCA: Display File Compiler......................135
  185.                 8.9. MR: Maximus Renumbering Program...................136
  186.                 8.10. ORACLE: Display File Viewer......................137
  187.                 8.11. SCANBLD: *.MSG Database Builder..................138
  188.                 8.12. SILT: Control File Compiler......................141
  189.                 8.13. SM: Session Monitor..............................142
  190.  
  191.              9. REXX User File Interface ..............................145
  192.                 9.1. Introduction......................................145
  193.                 9.2. Function Descriptions.............................146
  194.                 9.3. Accessing "usr." Variables........................153
  195.  
  196.              10. Introduction to MEX Programming ......................161
  197.                 10.1. About MEX........................................161
  198.                 10.2. MEX Road Map.....................................161
  199.                 10.3. Creating a Sample MEX Program....................162
  200.                 10.4. Compiling MEX Programs...........................165
  201.                 10.5. Running MEX Programs.............................166
  202.  
  203.              11. MEX Language Tutorial ................................169
  204.                 11.1. Program Development Cycle........................169
  205.                 11.2. Elements of a MEX Program........................171
  206.                 11.3. Variable Declarations............................174
  207.                 11.4. Variable Scope...................................178
  208.                 11.5. Preprocessor.....................................179
  209.                 11.6. Calculations and Arithmetic......................180
  210.  
  211.  
  212.  
  213.              Contents                                                    v
  214.  
  215.                 11.7. Displaying Output................................185
  216.                 11.8. Flow Control.....................................187
  217.                 11.9. Function Calls...................................194
  218.                 11.10. Arrays..........................................206
  219.                 11.11. Structures......................................214
  220.                 11.12. Casts...........................................223
  221.                 11.13. Further Explorations in MEX.....................225
  222.  
  223.              12. MEX for C and Pascal Programmers .....................227
  224.                 12.1. Comments.........................................227
  225.                 12.2. Include Files....................................227
  226.                 12.3. Blocks...........................................227
  227.                 12.4. Function Definitions.............................227
  228.                 12.5. Types............................................229
  229.                 12.6. Variable Declarations............................229
  230.                 12.7. Function Prototypes..............................229
  231.                 12.8. Function Return Values...........................229
  232.                 12.9. Strings..........................................229
  233.                 12.10. Compound Statements.............................230
  234.                 12.11. Arithmetic, Relational and Logical Operators....230
  235.                 12.12. The for Statement...............................231
  236.                 12.13. Arrays..........................................231
  237.                 12.14. Pointers........................................231
  238.                 12.15. Pass-By-Reference Arguments.....................232
  239.                 12.16. Variable-Length Arrays..........................232
  240.                 12.17. Structures......................................232
  241.                 12.18. Run-Time Library Support........................233
  242.  
  243.              13. Interfacing MEX with Maximus .........................235
  244.                 13.1. User Information.................................235
  245.                 13.2. Message Area Information.........................236
  246.                 13.3. File Area Information............................237
  247.                 13.4. Changing Message and File Areas..................237
  248.                 13.5. Displaying Output................................237
  249.                 13.6. Retrieving Input.................................238
  250.                 13.7. File I/O.........................................239
  251.                 13.8. Menu Commands, Displaying Files and External Programs
  252.                 .......................................................239
  253.                 13.9. Download Queue...................................239
  254.                 13.10. Other Functions.................................240
  255.  
  256.              14. MEX Compiler Reference ...............................241
  257.                 14.1. Command Line Format..............................241
  258.                 14.2. Environment Variables............................242
  259.                 14.3. Error Messages and Warnings......................242
  260.  
  261.              15. MEX Library Reference ................................251
  262.                 15.1. Global Variables and Data Structures.............251
  263.                 15.2. Functions by Category............................262
  264.                 15.3. Function Descriptions............................272
  265.  
  266.              16. MEX Language Reference ...............................351
  267.                 16.1. Operator Precedence..............................351
  268.  
  269.  
  270.  
  271.              Contents                                                   vi
  272.  
  273.                 16.2. Language Grammar.................................351
  274.  
  275.              17. MECCA Language Reference .............................355
  276.                 17.1. Usage Guide......................................355
  277.                 17.2. Color Token Listing..............................357
  278.                 17.3. Cursor Control and Video Tokens..................360
  279.                 17.4. Informational Tokens.............................362
  280.                 17.5. Questionnaire Token Listing......................366
  281.                 17.6. Privilege Level Controls.........................368
  282.                 17.7. Lock and Key Control.............................369
  283.                 17.8. Conditional and Flow Control Tokens..............370
  284.                 17.9. Multinode Tokens.................................378
  285.                 17.10. RIPscrip Graphics...............................379
  286.                 17.11. Miscellaneous Token Listing.....................381
  287.  
  288.              18. Control File Reference ...............................387
  289.                 18.1. SILT Directives..................................387
  290.                 18.2. System Control File..............................387
  291.                 18.3. Language Control File............................420
  292.                 18.4. Off-Line Reader Control File.....................421
  293.                 18.5. Colors Control File..............................422
  294.                 18.6. Message Area Control File........................424
  295.                 18.7. File Area Control File...........................430
  296.                 18.8. Menu Control File................................433
  297.                 18.9. Access Control File..............................450
  298.                 18.10. Protocol Control File...........................454
  299.                 18.11. Event File......................................459
  300.                 18.12. Language Translation File Reference.............461
  301.  
  302.              Appendices ...............................................463
  303.                 Appendix A: Common Problems............................463
  304.                 Appendix B: Error Messages.............................465
  305.                 Appendix C : Command Line Switches.....................468
  306.                 Appendix D: Local Keystrokes...........................471
  307.                 Appendix E: User Editor Keystrokes.....................473
  308.                 Appendix F: AVATAR Colors..............................474
  309.                 Appendix G: Sample BAT/CMD Files.......................475
  310.                 Appendix H: Support Files..............................481
  311.  
  312.              Index ....................................................485
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.                                                             1. Introduction
  323.  
  324.  
  325.              1.1. About Maximus
  326.  
  327.              Maximus is a flexible bulletin board package for the DOS and
  328.              OS/2 operating systems. Maximus allows remote users to con-
  329.              nect to the system by modem, read and write messages, par-
  330.              ticipate in public conference areas, send and receive files,
  331.              and much more.
  332.  
  333.              In addition to the standard message and file features found
  334.              in most BBS programs, Maximus also includes:
  335.  
  336.              *  MEX, an extension language that combines the best elements
  337.                 of the C, Pascal and BASIC languages. MEX includes support
  338.                 for advanced language features such as structures, arrays,
  339.                 dynamic strings, and pass-by-reference function arguments.
  340.                 MEX can be used to customize and extend Maximus in an infi-
  341.                 nite number of ways.
  342.  
  343.              *  MECCA, an easy-to-use scripting language that can be used
  344.                 to colorize screens and add simple menus and prompts to
  345.                 display files.
  346.  
  347.              *  Support for RIPscrip graphics. Maximus can detect RIPscrip
  348.                 capabilities, automatically size menu output based on the
  349.                 terminal window size, display most internal prompts using
  350.                 RIPscrip graphics, and much more.
  351.  
  352.              *  Support for SM, a Presentation Manager LAN monitoring tool
  353.                 for OS/2. SM can be used to manipulate and examine multiple
  354.                 Maximus sessions running on remote workstations.
  355.  
  356.              *  Full support for CD-ROMs and other slow filesystems. Maxi-
  357.                 mus will copy files to a staging area before a transfer and
  358.                 it will only access the drive when absolutely necessary.
  359.                 Areas can also be specifically excluded from new files
  360.                 searches.
  361.  
  362.              *  A message tracking system for use in technical support en-
  363.                 vironments. Maximus can keep an audit trail of all messages
  364.                 in certain areas, assign "ownership" of messages to indi-
  365.                 viduals, and produce detailed reports regarding the status
  366.                 of various messages.
  367.  
  368.              *  Support for an unlimited number of message and file areas.
  369.                 Maximus also supports "divisions" for constructing multi-
  370.                 level message and file area hierarchies.
  371.  
  372.  
  373.  
  374.              1. Introduction                                             2
  375.  
  376.              *  Support for a REXX user file interface. This interface can
  377.                 be used to read from and write to the Maximus user database
  378.                 from any OS/2-based REXX program.
  379.  
  380.              *  A powerful message "browse" feature that allows selection
  381.                 of messages based on user-defined search criteria.
  382.  
  383.              *  A built-in QWK mail subsystem that allows users to read and
  384.                 compose messages while off-line.
  385.  
  386.              *  Support for the Squish message format, a compact database
  387.                 for storing messages.
  388.  
  389.              *  Optional support for user password encryption. This feature
  390.                 uses the RSA Data Security, Inc. Message-Digest 5 algorithm
  391.                 as a one-way hash for storing passwords in the user file.
  392.  
  393.              *  Full multilingual support. The Maximus language file can be
  394.                 customized to support almost any language. Maximus also in-
  395.                 cludes special support for the Swedish 7-bit and the Chi-
  396.                 nese BIG5 character sets.
  397.  
  398.              *  An internal multinode chat facility, including virtual CB
  399.                 channels and private chatting between two nodes.
  400.  
  401.              *  An internal full-screen editor for composing messages.
  402.  
  403.              *  Internal file transfer protocols, including Zmodem, Ymodem-
  404.                 G and other popular protocols.
  405.  
  406.  
  407.              1.2. System Requirements
  408.  
  409.              This chapter describes the minimum hardware requirements for
  410.              a standard Maximus installation.
  411.  
  412.  
  413.              1.2.1. MS-DOS or PC-DOS Requirements
  414.  
  415.              The minimum system requirements for the DOS version of Maxi-
  416.              mus are:
  417.  
  418.              *  an IBM (or 100% compatible) personal computer with at least
  419.                 450K of available conventional RAM,
  420.  
  421.              *  MS-DOS or PC-DOS version 3.3 or greater, and
  422.  
  423.              *  A FOSSIL communications driver (revision level 5 or
  424.                 higher). (Common FOSSIL drivers are X00, BNU and OpusComm.)
  425.  
  426.  
  427.  
  428.              1. Introduction                                             3
  429.  
  430.              1.2.2. OS/2 Requirements
  431.  
  432.              The minimum system requirements for the OS/2 version of Maxi-
  433.              mus are:
  434.  
  435.              *  an IBM (or 100% compatible) personal computer with at least
  436.                 four megabytes of installed memory, and
  437.  
  438.              *  one of the following products:
  439.  
  440.                 * IBM OS/2, Version 2.0, 2.1 or 2.11
  441.                 * IBM OS/2 Warp, Version 3 or above
  442.                 * IBM OS/2 Warp Connect, Version 3 or above
  443.  
  444.              1.2.3. Common Requirements
  445.  
  446.              Regardless of the operating system type, the following hard-
  447.              ware is also required to run Maximus:
  448.  
  449.              *  A Hayes-compatible modem, 1200 bps or faster.
  450.  
  451.              *  A hard disk with at least 15 megabytes of free space. Addi-
  452.                 tional space is required to store the contents of file and
  453.                 message areas.
  454.  
  455.  
  456.              1.3. Typographical Conventions
  457.  
  458.              This document is provided in ASCII form for the convenience
  459.              of noncommercial users. However, the master version of this
  460.              document was designed and laid out for the bound version of
  461.              the Maximus documentation.
  462.  
  463.              The content is identical in these two versions of the manual.
  464.              However, a number of features and styles cannot be correctly
  465.              translated into the ASCII version of the document. In spe-
  466.              cific:
  467.  
  468.              *  The ASCII version of this document includes no lines, bor-
  469.                 ders, boldface, italics, shading, or sidebars.
  470.  
  471.              *  Indentation, table formatting, and hyphenation may not ap-
  472.                 pear correctly in the ASCII version.
  473.  
  474.              *  Typographical quotes are replaced with the ASCII equiva-
  475.                 lents.
  476.  
  477.              *  The ASCII version of the MEX and REXX documentation does
  478.                 not show the sideheads that appear in the printed version
  479.                 of the manual, including the "Prototype," "Arguments,"
  480.                 "Return Value," "Description" and "Example" headings.
  481.  
  482.  
  483.  
  484.              1. Introduction                                             4
  485.  
  486.              Please see the printed version of the manual for the official
  487.              layout and formatting.
  488.  
  489.  
  490.              1.4. Ordering a Printed Version of this Manual
  491.  
  492.              The commercial version of Maximus optionally comes with a
  493.              printed and bound version of this manual.
  494.  
  495.              However, even noncommercial users can order a copy of the
  496.              manual without purchasing the software itself.
  497.  
  498.              The printed manual is 466 pages long, perfect-bound (glued
  499.              back binding), dimensions 7" by 9", with a black and red
  500.              cover printed on glossy white card.
  501.  
  502.              To order a copy of the manual, please see the "MAXDOC" prod-
  503.              uct in the ORDER.FRM file (included in the distribution pack-
  504.              age).
  505.  
  506.  
  507.              1.5. Ordering Maximus for Commercial Use
  508.  
  509.              Maximus is completely free for noncommercial users. Most non-
  510.              commercial and private users can use Maximus without paying a
  511.              cent. To determine whether or not you are a commercial user,
  512.              please see the program license (contained in LICENSE.DOC).
  513.  
  514.              However, to use Maximus in a commercial environment, you must
  515.              obtain a commercial license from Lanius Corporation. For in-
  516.              formation on ordering a copy of Maximus, please see the order
  517.              form included in the Maximus distribution archive (called OR-
  518.              DER.FRM in MAX300C.ZIP).
  519.  
  520.              You can also contact Lanius at:
  521.  
  522.              FAX:   +1-613-634-3058        Post:     Lanius Corporation
  523.              email: sales@lanius.com                 777 Downing St.
  524.                                                      Kingston, Ont.
  525.                                                      CANADA  K7M 5N3
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.                                                         2. Maximus Overview
  535.  
  536.              This chapter provides a brief list of the commands and fea-
  537.              tures supported by Maximus 3.0. This list is by no means com-
  538.              plete, but it serves as a useful introduction to those System
  539.              Operators (SysOps) who are unfamiliar with Maximus.
  540.  
  541.  
  542.              2.1. Waiting for Callers
  543.  
  544.              When Maximus is set up to handle remote callers, it enters
  545.              "Waiting for Caller" (WFC) mode as soon as the system is
  546.              started. In this mode, Maximus initializes the modem and in-
  547.              structs it to wait for incoming calls.
  548.  
  549.              When a ring is detected, the modem answers the phone. If a
  550.              connection is successfully established, Maximus waits until
  551.              the user presses <enter> twice, or until five seconds have
  552.              elapsed, whichever occurs sooner.
  553.  
  554.  
  555.              2.2. Logging On
  556.  
  557.              After a connection is established, Maximus displays the sys-
  558.              tem name and version, followed by any information that the
  559.              SysOp has placed in the log-on display file,
  560.              \max\misc\logo.mec. This screen must not include any graphics
  561.              commands or high-bit characters, since Maximus has not yet
  562.              determined the graphics capabilities of the caller.
  563.  
  564.              Maximus then prompts the user for a name. Unlike other BBS
  565.              programs, Maximus allows more than two words in a username,
  566.              so names such as "John Q. Public" are perfectly acceptable.
  567.              However, Maximus rejects callers with one-word names unless
  568.              the Single Word Names feature is enabled.
  569.  
  570.              If the user does not exist in the user file, Maximus displays
  571.              the \max\misc\notfound.mec file. This file normally informs
  572.              the user that no existing user record with the specified name
  573.              could be found, and it normally indicates that a new account
  574.              will be created if the user continues with the log-on proc-
  575.              ess.
  576.  
  577.              Next, Maximus displays a prompt to ensure that the user's
  578.              name was entered correctly. Given input of "John Doe", Maxi-
  579.              mus will respond with:
  580.  
  581.                 John Doe [Y,n]?
  582.  
  583.  
  584.  
  585.              2. Maximus Overview                                         6
  586.  
  587.              If the username was spelled incorrectly, the user can enter
  588.              "n" and begin the log-on process again.
  589.  
  590.  
  591.              2.2.1. Log-on Process for Existing Users
  592.  
  593.              If the name of an existing user is entered, Maximus prompts
  594.              the user to enter the password for that user account. The
  595.              user has up to five tries to enter the correct password. If
  596.              none of the five attempts are successful, Maximus displays
  597.              the \max\misc\bad_pwd.mec file. By default, this file allows
  598.              the user to leave a message to the SysOp before the system
  599.              hangs up.
  600.  
  601.              Once Maximus validates the password entered by the user, it
  602.              displays the \max\misc\welcome.mec file. This file can con-
  603.              tain ANSI or RIPscrip graphics to be shown to the user.
  604.  
  605.  
  606.              2.2.2. Log-On Process for New Users
  607.  
  608.              If the user enters the correct password, Maximus validates
  609.              the user and displays the \max\misc\welcome.mec file.
  610.  
  611.              If a non-existent username is entered, Maximus enters the
  612.              "new user" state. In this state, Maximus first displays the
  613.              \max\misc\applic.mec file, which normally gives the caller
  614.              some information about the system. This file can also present
  615.              an application form to be filled out by the user.
  616.  
  617.              Maximus will then prompt for the user's city and
  618.              state/province, alias, phone number, and a number of other
  619.              user settings.
  620.  
  621.              Lastly, Maximus will display \max\misc\newuser2.mec. This
  622.              file typically describes the system in more detail.
  623.  
  624.  
  625.              2.3. Command Stacking
  626.  
  627.              Maximus allows the user to stack command responses by enter-
  628.              ing multiple words at an input prompt. This feature is nor-
  629.              mally used to expedite the log-on process, but command stack-
  630.              ing can also be used for most other Maximus commands.
  631.  
  632.              Without command stacking, a typical log-on sequence looks
  633.              like this:
  634.  
  635.                 What is your name: John Doe
  636.  
  637.                 John Doe [Y,n]? y
  638.  
  639.                 Password: ......
  640.  
  641.  
  642.  
  643.              2. Maximus Overview                                         7
  644.  
  645.  
  646.              Instead of entering each of these responses separately, all
  647.              of the responses can be placed on the same line, as shown be-
  648.              low:
  649.  
  650.                 What is your name: John Doe;y;password
  651.  
  652.              Maximus also supports command line editing at most system
  653.              prompts. After the user has logged on, and as long as ANSI or
  654.              AVATAR graphics are enabled, the user can use the cursor keys
  655.              to edit any of the text on the command line. Editing can be
  656.              performed using the <left>, <right>, <bs>, <del>, <ctrl-
  657.              left>, and <ctrl-right> keys.
  658.  
  659.              To use the command line editing feature from remote, the
  660.              user's terminal program must support either "Doorway mode" or
  661.              VT-100 keyboard codes.
  662.  
  663.  
  664.              2.4. Guest Accounts
  665.  
  666.              If the SysOp uses the user editor to create an account that
  667.              has no password, Maximus treats it as a guest account. If a
  668.              user logs on using a guest account, Maximus automatically
  669.              skips the password prompt. In addition, Maximus prompts the
  670.              guest user for a new set of configuration options at the be-
  671.              ginning of every log-on, including editor preference, graph-
  672.              ics support, and more.
  673.  
  674.              This feature allows the SysOp to specifically create a single
  675.              account for new users, even if the Logon Level Preregistered
  676.              feature is enabled. This feature is useful when the SysOp
  677.              wants potential users to fill out an application form (using
  678.              the guest account) before granting access to the system.
  679.  
  680.  
  681.              2.5. The Main Menu
  682.  
  683.              After displaying the log-on screens, Maximus also displays
  684.              the text in the \max\misc\bulletin.mec file. This file typi-
  685.              cally contains system bulletins or other messages of interest
  686.              to all users.
  687.  
  688.              Following the system bulletins, the user is placed at the
  689.              main menu. Although Maximus's menus are completely customiza-
  690.              ble, this section describes the commands that are found on
  691.              the main menu in the default configuration.
  692.  
  693.              Message Section
  694.  
  695.                 This command takes the user to the message section. The
  696.                 message section is used to participate in public conference
  697.  
  698.  
  699.  
  700.              2. Maximus Overview                                         8
  701.  
  702.                 areas and to enter messages to other users. Please see sec-
  703.                 tion 2.6 for more information.
  704.  
  705.              File Section
  706.  
  707.                 This command takes the user to the file section. The file
  708.                 section contains libraries of files that can be downloaded
  709.                 (retrieved). The user can also upload (send) files, search
  710.                 for files of a specific name, and display a file list.
  711.                 Please see section 2.7 for more information.
  712.  
  713.              Change Setup
  714.  
  715.                 This takes the user to the change setup section. This menu
  716.                 allows users to adjust settings in their user profiles. The
  717.                 user can change the screen width and length, select a de-
  718.                 fault file transfer protocol, change telephone numbers, and
  719.                 more. Please see section 2.8 for more information.
  720.  
  721.              Goodbye
  722.  
  723.                 This option logs the user off and hangs up the phone. Even
  724.                 if the user does not log off using this command, Maximus
  725.                 will still update the user's user record. However, this
  726.                 command gives the user the opportunity to leave a comment
  727.                 to the SysOp.
  728.  
  729.                 Comments to the SysOp are placed in the message area speci-
  730.                 fied by the Comment Area keyword in the system control
  731.                 file.
  732.  
  733.                 The subject used for the log-off comment can be set in the
  734.                 comment_fr string in the Maximus language file. This string
  735.                 can include external program translation characters. Please
  736.                 see section 6 for more information.
  737.  
  738.              Statistics
  739.  
  740.                 This command displays the user's statistics, including the
  741.                 time of day, the length of the current call, the user's to-
  742.                 tal time for the day, number of kilobytes uploaded and
  743.                 downloaded, and so on.
  744.  
  745.              Yell
  746.  
  747.                 This command allows the user to request a conversation with
  748.                 the SysOp. By default, this command plays a simple tune on
  749.                 the system speaker. (This tune can be configured in the
  750.                 \max\tunes.bbs file.) The local speaker can also be toggled
  751.                 on and off by pressing "!" at the local console while a
  752.                 user is logged on.
  753.  
  754.  
  755.  
  756.              2. Maximus Overview                                         9
  757.  
  758.         OS/2    Maximus can also play yell tunes on a SoundBlaster or
  759.        only!    SoundBlaster-compatible device. Please see section 18.11
  760.                 for more information.
  761.  
  762.              Userlist
  763.  
  764.                 This command displays the list of all records in the user
  765.                 file. Users can exclude themselves from this list using the
  766.                 "InUserList" command on the Change Setup menu. In addition,
  767.                 the SysOp can modify the access control file to restrict
  768.                 the user list display to a certain set of privilege levels.
  769.  
  770.              Version
  771.  
  772.                 This command displays the Maximus version number and copy-
  773.                 right information.
  774.  
  775.              SysOp Menu
  776.  
  777.                 This command takes the user to the SysOp menu. Normally,
  778.                 only the system operator or a trusted user will have access
  779.                 to this command. Please see section 2.9 for more informa-
  780.                 tion.
  781.  
  782.              Chat Menu
  783.  
  784.                 This command takes the user to the multinode chat menu.
  785.                 This menu allows the user to access all of Maximus's multi-
  786.                 node features, including paging, toggling chat availabil-
  787.                 ity, and private/public chatting. (This command is used ex-
  788.                 clusively to allow users to communicate among themselves.
  789.                 The Yell command is used to chat with the SysOp.)
  790.  
  791.              Who is On?
  792.  
  793.                 This command displays a list of callers who are currently
  794.                 logged onto the system. The Who is On? display includes
  795.                 each user's name, status, and chat availability.
  796.  
  797.              At the SysOp's discretion, other options and submenus can be
  798.              added to the main menu. Please see section 18.8 for more in-
  799.              formation on adding menu options.
  800.  
  801.  
  802.              2.6. The Message Section
  803.  
  804.              Maximus supports four distinct message area types: local ar-
  805.              eas, NetMail areas, EchoMail areas, and conference areas.
  806.  
  807.              Local areas are used for messages that are local to your BBS.
  808.              These messages can be public or private, but local messages
  809.              do not get transmitted to other bulletin boards.
  810.  
  811.  
  812.  
  813.              2. Maximus Overview                                        10
  814.  
  815.              NetMail areas are used for private, point-to-point communica-
  816.              tion between users on two FidoNet-compatible systems. When
  817.              entering a message in a NetMail area, Maximus prompts the
  818.              user for additional addressing information, including the
  819.              destination address of the message and (optionally) a number
  820.              of message handling attributes. Maximus also maintains a
  821.              "NetMail credit" account for each user that can be used when
  822.              billing users for NetMail usage.
  823.  
  824.              Conference areas and EchoMail areas (also known as echoes)
  825.              are used for public conferences that are distributed among
  826.              many systems. A message entered in an EchoMail area is broad-
  827.              cast to all of the systems which carry that conference. To a
  828.              Maximus user, an EchoMail area appears identical to a local
  829.              message area, except that messages entered in EchoMail areas
  830.              have network control information added to the end of the mes-
  831.              sage. In addition, after a user enters a message in an
  832.              EchoMail area, Maximus adds the name of that area to the Log
  833.              EchoMail file. This file can be used later by a scanning pro-
  834.              gram, such as Squish, to export that message to the rest of
  835.              the network.
  836.  
  837.              In addition to defining the message area type, a number of
  838.              message area attributes can be assigned to each message area.
  839.              A complete listing of these attributes can be found in sec-
  840.              tion 18.6, but some of the more common attributes are given
  841.              below:
  842.  
  843.              Pvt
  844.  
  845.                 All messages entered in this area will be marked private.
  846.                 Private messages can only be read by the message sender and
  847.                 the addressee. (Users in a privilege level class that has
  848.                 the ShowPvt flag can also read private messages addressed
  849.                 to any user. Typically, these permissions are only granted
  850.                 to the SysOp.)
  851.  
  852.              Pub
  853.  
  854.                 All messages entered in these areas are marked as public.
  855.                 Regardless of the addressee of the message, any user can
  856.                 read a public message. If both the Pvt and Pub attributes
  857.                 are specified, the user can enter either public or private
  858.                 messages.
  859.  
  860.              ReadOnly
  861.  
  862.                 The SysOp can place messages in a read-only area, but nor-
  863.                 mal users are unable to post messages in areas of this
  864.                 type. (Users in a privilege level class that has the
  865.                 WriteRdOnly flag can also post messages in this area.)
  866.  
  867.  
  868.  
  869.              2. Maximus Overview                                        11
  870.  
  871.              Anon
  872.  
  873.                 When a user enters a message in an area with the Anon at-
  874.                 tribute set, Maximus prompts the user to enter the From:
  875.                 field of the message. (In all other areas, Maximus auto-
  876.                 matically fills in the From: field with the user's real
  877.                 name.)
  878.  
  879.                 However, Maximus can optionally embed the user's real name
  880.                 within the message such that the SysOp can read it if nec-
  881.                 essary. This option is enabled by default. See the Style
  882.                 NoNameKludge flag in section 18.6 for more information.
  883.  
  884.              Attach
  885.  
  886.                 Message areas with this attribute allow users to attach
  887.                 files to messages created in the area. Please see the de-
  888.                 scription of the Enter Message command in section 2.6 for
  889.                 more information. Also see section 5.2 for information on
  890.                 local file attaches.
  891.  
  892.              The SysOp can also assign passwords to message and file ar-
  893.              eas, enable message tracking, add support for high-bit char-
  894.              acters, and more. Access to individual message areas can also
  895.              be granted based on a user's privilege level or name. Please
  896.              see section 18.6 for more information.
  897.  
  898.  
  899.              2.6.1. The Message Menu
  900.  
  901.              This section describes the commands that are found on the
  902.              standard message menu:
  903.  
  904.              Area Change
  905.  
  906.                 This command allows the user to select another message
  907.                 area. The user can select an area by name, but the "[" and
  908.                 "]" keys can be used to select the message areas which pre-
  909.                 cede or follow the current area, respectively.
  910.  
  911.                 The "?" character displays a list of areas. For navigating
  912.                 within a hierarchical area structure, the "/" key moves to
  913.                 the top-level menu, and the ".." sequence ascends one level
  914.                 in the menu tree.
  915.  
  916.              Next
  917.  
  918.                 This command displays the next message in the current area.
  919.                 After displaying a message with the Next command, pressing
  920.                 <enter> at the message area prompt automatically displays
  921.                 the next message.
  922.  
  923.  
  924.  
  925.              2. Maximus Overview                                        12
  926.  
  927.              Previous
  928.  
  929.                 This command displays the prior message in the current
  930.                 area. After displaying a message with the Prior command,
  931.                 pressing <enter> at the message area prompt will automati-
  932.                 cally display the prior message.
  933.  
  934.              Enter a Message
  935.  
  936.                 This command allows a user to enter (post) a message in the
  937.                 current message area. Maximus first prompts the user to
  938.                 fill out the message header, including the To field, the
  939.                 Subject field, and the message attributes.
  940.  
  941.                 For users who have ANSI, AVATAR or RIPscrip graphics en-
  942.                 abled, Maximus displays a message header with fields that
  943.                 can be filled out by the user. The <up> and <down> keys can
  944.                 be used to move between fields, as can the <shift-tab> and
  945.                 <tab> keys.
  946.  
  947.                 If the message area definition permits both public and pri-
  948.                 vate messages, Maximus allows the user to select either
  949.                 type of message. For users who have graphics enabled, the
  950.                 private flag can be toggled by pressing <space> when the
  951.                 cursor is on the attributes field (above the message date)
  952.                 The P key also has the same effect.
  953.  
  954.                 In areas which support file attachments, a file can be at-
  955.                 tached to a message by pressing the A key while the cursor
  956.                 is on the attributes field. (Maximus will prompt the user
  957.                 to upload the file after the message has been created.)
  958.  
  959.                 In Local areas, the user can obtain the system user list by
  960.                 pressing ? at the To prompt. Maximus normally generates
  961.                 this list automatically from the system user file, but if a
  962.                 \max\misc\userlist.mec file exists, Maximus will display it
  963.                 instead of the real user list.
  964.  
  965.                 In NetMail areas, the attributes field can also be used to
  966.                 select other mail handling options. Entering a ? at the at-
  967.                 tribute prompt gives a complete list of keys.
  968.  
  969.                 In addition, NetMail areas also allow the user to select
  970.                 the destination address for the message.
  971.  
  972.                 After entering the message header information, Maximus will
  973.                 run the system editor and allow the user to enter the body
  974.                 of the message.
  975.  
  976.  
  977.  
  978.              2. Maximus Overview                                        13
  979.  
  980.              Change a Message
  981.  
  982.                 This command allows the user to modify an existing message.
  983.                 Although the SysOp can modify any message on the system, a
  984.                 normal user can only modify messages which:
  985.  
  986.                 * have not been read by the recipient,
  987.  
  988.                 * have not been sent (in the case of NetMail or EchoMail),
  989.                   and
  990.  
  991.                 * have the user's name in the From field.
  992.  
  993.                 Both the message header and the message body can be modi-
  994.                 fied. When graphics are enabled, the user can also modify
  995.                 the message attributes.
  996.  
  997.              Reply to Message
  998.  
  999.                 This command allows the user to enter a response to the
  1000.                 currently-selected message. The Reply command is similar to
  1001.                 the Enter command; however, Maximus will automatically fill
  1002.                 out the fields in the message header when doing a Reply. In
  1003.                 addition, Maximus will also adjust the message reply chain
  1004.                 so that the new message is marked as a reply to the origi-
  1005.                 nal message.
  1006.  
  1007.                 Within the message editor, the user can also quote (copy)
  1008.                 text from the original message into the newly-created re-
  1009.                 ply.
  1010.  
  1011.              Read Non-Stop
  1012.  
  1013.                 This command displays a number of messages all at once,
  1014.                 with no pauses or prompts between messages. If the user
  1015.                 last selected the Next command, Maximus displays all mes-
  1016.                 sages from the current message to the last message in the
  1017.                 area. Otherwise, if the user last selected the Prior com-
  1018.                 mand, Maximus displays all messages from the current mes-
  1019.                 sage to the first message in the area (in reverse order).
  1020.  
  1021.              Read Original
  1022.  
  1023.                 This command examines the current message and finds the
  1024.                 original message in the reply thread. (If the current mes-
  1025.                 sage was a reply to another message, this command displays
  1026.                 that other message.) Messages that are replies to other
  1027.                 messages have a "*** This is a reply to #msg" line at the
  1028.                 bottom of the message or a "- msg" field in the message
  1029.                 header.
  1030.  
  1031.  
  1032.  
  1033.              2. Maximus Overview                                        14
  1034.  
  1035.              Read Reply
  1036.  
  1037.                 This command displays the message which is a reply to the
  1038.                 current message, if any. Messages which have replies have a
  1039.                 "*** See also #msg" line at the bottom of the message or a
  1040.                 "+ msg" field in the message header.
  1041.  
  1042.              Read Current
  1043.  
  1044.                 This command redisplays the current message.
  1045.  
  1046.              Browse
  1047.  
  1048.                 This command scans any or all of the message areas on the
  1049.                 system and retrieves selected messages. Browse acts as a
  1050.                 powerful database engine for the message bases. Users can
  1051.                 select a set of messages and operations to perform, and
  1052.                 then have Maximus automatically identify and display the
  1053.                 messages that were requested.
  1054.  
  1055.                 The first browse menu prompts the user to select a set of
  1056.                 message areas. The user can select any of:
  1057.  
  1058.                 * the current area,
  1059.                 * all message areas,
  1060.                 * all tagged message areas,
  1061.                 * a wildcard specification (such as "comp.lang.*"), or
  1062.                 * the current group (all areas which are on the same level
  1063.                   in the message area hierarchy)
  1064.  
  1065.                 The second browse menu prompts the user to select a type of
  1066.                 message. The user can specify:
  1067.  
  1068.                 * all messages,
  1069.                 * new messages (those which are above the user's lastread
  1070.                   pointer),
  1071.                 * your messages (unread messages which are addressed to
  1072.                   the user and which are above the user's lastread
  1073.                   pointer), and
  1074.                 * from a certain message number (such as from message 500
  1075.                   to the end of the area).
  1076.  
  1077.                 Maximus also allows the user to perform a search based on
  1078.                 keywords in the To, From and Subject fields, in addition to
  1079.                 searching the message body. Complex searches can be defined
  1080.                 by combining the logical or and and operators.
  1081.  
  1082.                 The third and final browse menu prompts the user to specify
  1083.                 an operation to perform on the selected messages. Messages
  1084.                 can be:
  1085.  
  1086.                 * listed (one to a line, with to/from/subject only),
  1087.  
  1088.  
  1089.  
  1090.              2. Maximus Overview                                        15
  1091.  
  1092.                 * read (displayed in full, with the option to reply or
  1093.                   kill each message), or
  1094.                 * packed (compressed into a QWK packet for download and
  1095.                   off-line mail reading).
  1096.  
  1097.              Tag
  1098.  
  1099.                 This command allows users to select a subset of the message
  1100.                 areas on the system. Each user can select his or her own
  1101.                 set of personal message areas. This area selection is used
  1102.                 to control the areas scanned by the Browse command and the
  1103.                 off-line message reader.
  1104.  
  1105.              Edit User
  1106.  
  1107.                 This command reads in the current message, checks the From
  1108.                 field, invokes the system user editor, and automatically
  1109.                 positions the user editor on that user's user record. This
  1110.                 option is useful for validating users, since a user's user
  1111.                 record can be displayed at the press of a key. (This com-
  1112.                 mand is normally only available to SysOps.)
  1113.  
  1114.                 To invoke the user editor without seeking to a specific
  1115.                 user, instead use the User Edit command from the SysOp
  1116.                 menu.
  1117.  
  1118.              Goodbye
  1119.  
  1120.                 This option logs the user off and hangs up the phone. Even
  1121.                 if the user does not log off using this command, Maximus
  1122.                 will still update the user's user record. However, this
  1123.                 command gives the user the opportunity to leave a comment
  1124.                 to the SysOp.
  1125.  
  1126.                 Comments to the SysOp are placed in the message area speci-
  1127.                 fied by the Comment Area keyword in the system control
  1128.                 file.
  1129.  
  1130.                 The subject used for the log-off comment can be set in the
  1131.                 comment_fr string in the Maximus language file. This string
  1132.                 can include external program translation characters. Please
  1133.                 see section 6 for more information.
  1134.  
  1135.              Main Menu
  1136.  
  1137.                 This command returns the user to the main menu.
  1138.  
  1139.              Kill a Message
  1140.  
  1141.                 This command allows the user to delete a message from the
  1142.                 current area. A normal user can only delete messages which
  1143.                 contain that user's name in either the To or the From field
  1144.  
  1145.  
  1146.  
  1147.              2. Maximus Overview                                        16
  1148.  
  1149.                 of the message to be deleted. However, the SysOp can delete
  1150.                 any message on the system.
  1151.  
  1152.              Upload a Message
  1153.  
  1154.                 This command allows the user to directly upload a text file
  1155.                 as a message. This command is identical to the Enter com-
  1156.                 mand, except that Maximus prompts the user to start a file
  1157.                 transfer protocol instead of invoking one of the system
  1158.                 editors.
  1159.  
  1160.              Forward
  1161.  
  1162.                 This command allows the user to copy a message in the cur-
  1163.                 rent area and send it to someone else. Maximus prompts the
  1164.                 user to enter the message number to be forwarded and the
  1165.                 name of the addressee.
  1166.  
  1167.                 The user can also forward the message directly into another
  1168.                 area by typing the area number when prompted. The Forward
  1169.                 command also supports two special modifiers:
  1170.  
  1171.                 * Entering FK from the message area menu instructs Maximus
  1172.                   to delete the original message after it has been for-
  1173.                   warded.
  1174.  
  1175.                 * Entering FB from the message area menu instructs Maximus
  1176.                   to send a "bombing run." Maximus prompts the user to
  1177.                   specify a local filename that contains a list of message
  1178.                   addressees. (In order to use this command, the user's
  1179.                   privilege level must be equal to the level required to
  1180.                   create a message from a file, as defined by the Message
  1181.                   Edit Ask FromFile keyword in the system control file.)
  1182.  
  1183.                   The format of each line of the bombing run file is as
  1184.                   follows:
  1185.  
  1186.                   <username> <dest_net/dest_node> [-x]
  1187.  
  1188.                   The <dest_net/dest_node> and [-x] fields are only used
  1189.                   for NetMail messages and should be omitted for local
  1190.                   bombing runs.
  1191.  
  1192.                   -x can be one of the switches shown below in Table 2.1:
  1193.  
  1194.                   Table 2.1 Bombing Run Options
  1195.  
  1196.                    Switch  Description
  1197.  
  1198.                    -h      The message should be marked as "hold for
  1199.                            pickup."
  1200.                    -c      The message should be marked as "crash."
  1201.  
  1202.  
  1203.  
  1204.              2. Maximus Overview                                        17
  1205.  
  1206.                    -n      The message should sent normally (default)
  1207.  
  1208.  
  1209.                   In the username field, spaces in a user's name must be
  1210.                   represented by underscores.
  1211.  
  1212.                   For example:
  1213.  
  1214.                   SysOp               1:225/337
  1215.                   Scott_Dudley        1:249/106 -c
  1216.                   Bob_Davis           1:106/114 -h
  1217.                   Vince_Perriello     1:141/191 -n
  1218.  
  1219.        Note!      If you are performing a NetMail bombing run, it is cour-
  1220.                   teous to send all messages directly to the destination
  1221.                   (without routing your mail through other systems).
  1222.  
  1223.              Hurl
  1224.  
  1225.                 This command moves messages from one area to another. The
  1226.                 Hurl command asks the user for the destination area and the
  1227.                 number of the message to be moved.
  1228.  
  1229.              Xport
  1230.  
  1231.                 This command exports a message to a specific path and file-
  1232.                 name on the local system. (The Xport command is normally
  1233.                 only available to SysOps.)
  1234.  
  1235.                 The exported message includes a copy of the message header.
  1236.                 The message body is formatted for an 80-column screen.
  1237.  
  1238.                 To print a message on the printer, specify an Xport file-
  1239.                 name of "prn".
  1240.  
  1241.              In addition, other menu options can be placed on the message
  1242.              menu, including commands to call auxiliary menus, display
  1243.              text files, and run external programs. Please see section
  1244.              18.8 for more information.
  1245.  
  1246.  
  1247.              2.6.2. Message Editors
  1248.  
  1249.              Maximus has two internal message editors: MaxEd, the full
  1250.              screen editor, and BORED, the line-oriented editor. Maximus
  1251.              also supports a single, SysOp-defined external message edi-
  1252.              tor.
  1253.  
  1254.  
  1255.              2.6.2.1. MaxEd
  1256.  
  1257.              MaxEd is the Maximus full screen editor. To use MaxEd, the
  1258.              user must have ANSI, AVATAR or RIPscrip graphics enabled,
  1259.  
  1260.  
  1261.  
  1262.              2. Maximus Overview                                        18
  1263.  
  1264.              have a screen width of 80 columns, and have a screen length
  1265.              of at least 23 rows. The full screen editor has a number of
  1266.              advantages over the line editor, with the most obvious being
  1267.              that it is much easier to use. MaxEd is more like a word
  1268.              processor than a conventional BBS line editor; the cursor
  1269.              keys can be used to page through a message and insert or de-
  1270.              lete text at various points in the message.
  1271.  
  1272.              For editing messages, MaxEd uses a mixture of WordStar and
  1273.              generic VT-100 keystrokes. A full list of the keys used by
  1274.              MaxEd can be obtained by pressing <ctrl-n> from within the
  1275.              editor.
  1276.  
  1277.              When composing a reply to another message, text from the
  1278.              original message can also be quoted (copied) into the reply.
  1279.              The <ctrl-k>R sequence (or <alt-q> on the local keyboard)
  1280.              toggles the quote window display.
  1281.  
  1282.              To scroll the quote window down by four lines, press either
  1283.              <ctrl-c> or <pgdn>.
  1284.  
  1285.              To scroll the quote window up by four lines, press either
  1286.              <ctrl-r> or <pgup>.
  1287.  
  1288.              To copy text from the quote window into the message, press
  1289.              either <ctrl-k>C or <alt-c>. Maximus will copy the text and
  1290.              automatically scroll the quote window down by four lines.
  1291.  
  1292.              MaxEd also has its own menu that allows the user to modify
  1293.              the fields in the message header. This menu can be accessed
  1294.              by pressing either <ctrl-k>H or <f10>.
  1295.  
  1296.              The options available on the MaxEd menu include:
  1297.  
  1298.              Continue
  1299.  
  1300.                 This command returns the user to the MaxEd's message-
  1301.                 editing screen.
  1302.  
  1303.              To
  1304.  
  1305.                 This command allows the user to change the addressee of the
  1306.                 message.
  1307.  
  1308.              Subject
  1309.  
  1310.                 This command allows the user to change the subject of the
  1311.                 message.
  1312.  
  1313.              From
  1314.  
  1315.                 This command allows the user to change the From field of
  1316.                 the message. The privilege level of this command should be
  1317.  
  1318.  
  1319.  
  1320.              2. Maximus Overview                                        19
  1321.  
  1322.                 set high enough so that only the SysOp can access this com-
  1323.                 mand.
  1324.  
  1325.              Handling
  1326.  
  1327.                 This command allows the user to modify the message's at-
  1328.                 tributes. Attributes such as the Private flag can be
  1329.                 changed, in addition to NetMail attributes (such as Crash,
  1330.                 Hold and File Attach). This option is normally only avail-
  1331.                 able to the SysOp.
  1332.  
  1333.              Read File
  1334.  
  1335.                 This command allows the user to read in a file from the lo-
  1336.                 cal hard drive and include it as part of the message. This
  1337.                 option is normally only available to the SysOp.
  1338.  
  1339.  
  1340.              2.6.2.2. BORED
  1341.  
  1342.              BORED is the Maximus line editor. Unlike MaxEd, BORED does
  1343.              not require ANSI or AVATAR graphics, so it can be used by any
  1344.              user. (However, most users who have graphics capabilities
  1345.              will likely prefer to use MaxEd.)
  1346.  
  1347.              BORED allows the user to enter a message one line at a time.
  1348.              If the user presses <enter> on a blank line, BORED displays
  1349.              the editor menu. The following editor commands are available:
  1350.  
  1351.              Save
  1352.  
  1353.                 This command saves the message and returns to the message
  1354.                 menu.
  1355.  
  1356.              Abort
  1357.  
  1358.                 This command aborts (discards) the message and returns to
  1359.                 the message menu.
  1360.  
  1361.              List
  1362.  
  1363.                 This command lists the message. Each line in the message is
  1364.                 indicated by number.
  1365.  
  1366.              Edit
  1367.  
  1368.                 This command is used to replace text in a message. First,
  1369.                 Maximus prompts the user to enter the line number which
  1370.                 contains the text to be replaced. Next, the user enters the
  1371.                 search text (the text which is to be replaced). Finally,
  1372.                 the user enters the replacement text.
  1373.  
  1374.  
  1375.  
  1376.              2. Maximus Overview                                        20
  1377.  
  1378.                 To insert text at the beginning of a line, simply press
  1379.                 <enter> at the Text to replace: prompt.
  1380.  
  1381.              Insert
  1382.  
  1383.                 This command inserts a blank line in the message. The user
  1384.                 can specify a line number to indicate where the blank line
  1385.                 is to be placed.
  1386.  
  1387.              Delete
  1388.  
  1389.                 This command deletes a specified line in the message.
  1390.  
  1391.              Continue
  1392.  
  1393.                 This command allows the user to continue writing by append-
  1394.                 ing new lines to the end of the message.
  1395.  
  1396.              Quote
  1397.  
  1398.                 For messages which are replies, this command allows the
  1399.                 user to quote text from the original message. Maximus
  1400.                 prompts the user to enter the starting and ending line num-
  1401.                 bers (in the original message) for the text to be quoted.
  1402.  
  1403.              To
  1404.  
  1405.                 This command allows the user to change the addressee of the
  1406.                 message.
  1407.  
  1408.              Subject
  1409.  
  1410.                 This command allows the user to change the subject of the
  1411.                 message.
  1412.  
  1413.              From
  1414.  
  1415.                 This command allows the user to change the From field of
  1416.                 the message. The privilege level of this command should be
  1417.                 set high enough so that only the SysOp can access this com-
  1418.                 mand.
  1419.  
  1420.              Handling
  1421.  
  1422.                 This command allows the user to modify the message's at-
  1423.                 tributes. Attributes such as the Private flag can be
  1424.                 changed, in addition to NetMail attributes (such as Crash,
  1425.                 Hold and File Attach). This option is normally only avail-
  1426.                 able to the SysOp.
  1427.  
  1428.  
  1429.  
  1430.              2. Maximus Overview                                        21
  1431.  
  1432.              Read File From Disk
  1433.  
  1434.                 This command allows the user to read in a file from the lo-
  1435.                 cal hard drive and include it as part of the message. This
  1436.                 option is normally only available to the SysOp.
  1437.  
  1438.  
  1439.              2.7. The File Menu
  1440.  
  1441.              This section describes the commands that are found on the
  1442.              standard file menu:
  1443.  
  1444.              Area Change
  1445.  
  1446.                 This command allows the user to select another file area.
  1447.                 The user can select an area by name, but the "[" and "]"
  1448.                 keys can be used to select the areas which precede or fol-
  1449.                 low the current area, respectively.
  1450.  
  1451.                 The "?" character displays a list of file areas. For navi-
  1452.                 gating within a hierarchical area structure, the "/" key
  1453.                 can be used to go to the top-level menu, and the ".." se-
  1454.                 quence can be used to ascend one level in the menu tree.
  1455.  
  1456.              Locate
  1457.  
  1458.                 This command allows the user to search all file areas on
  1459.                 the system for a specific file.
  1460.  
  1461.                 Maximus first prompts the user to enter a text string.
  1462.                 Next, it will go through all of the file areas on the sys-
  1463.                 tem, and if it finds a match for that string (in either a
  1464.                 filename or file description), it will display the name of
  1465.                 the area and the corresponding file information.
  1466.  
  1467.                 The L* command instructs Maximus to search all file areas
  1468.                 for new files. This command will display a list of files
  1469.                 that have been added to the system since the last L* com-
  1470.                 mand was executed.
  1471.  
  1472.              File Titles
  1473.  
  1474.                 This command displays a list of files in the current area.
  1475.                 New files are identified by a flashing asterisk (*) next to
  1476.                 the file date.
  1477.  
  1478.                 If the user specifies an argument when invoking this com-
  1479.                 mand, the File Titles command displays only those files
  1480.                 which contain that string in the filename or description
  1481.                 fields. (However, the File Titles command only searches the
  1482.                 current file area, whereas the Locate command searches all
  1483.                 file areas.)
  1484.  
  1485.  
  1486.  
  1487.              2. Maximus Overview                                        22
  1488.  
  1489.                 In addition, when the More [Y,n,t,=]? prompt is displayed
  1490.                 during a file list, the "t" option (if present) allows the
  1491.                 user to tag files for download. This option is only dis-
  1492.                 played if the user has an access level high enough to allow
  1493.                 file downloading.
  1494.  
  1495.              View
  1496.  
  1497.                 This command displays the contents of an ASCII file in the
  1498.                 current area. Before displaying the file to the user, Maxi-
  1499.                 mus first checks the file to ensure that it contains only
  1500.                 ASCII text.
  1501.  
  1502.              Goodbye
  1503.  
  1504.                 This option logs the user off and hangs up the phone. Even
  1505.                 if the user does not log off using this command, Maximus
  1506.                 will still update the user's user record. However, this
  1507.                 command gives the user the opportunity to leave a comment
  1508.                 to the SysOp.
  1509.  
  1510.                 Comments to the SysOp are placed in the message area speci-
  1511.                 fied by the Comment Area keyword in the system control
  1512.                 file.
  1513.  
  1514.                 The subject used for the log-off comment can be set in the
  1515.                 comment_fr string in the Maximus language file. This string
  1516.                 can include external program translation characters. Please
  1517.                 see section 6 for more information.
  1518.  
  1519.              Main Menu
  1520.  
  1521.                 This command returns the user to the main menu.
  1522.  
  1523.              Download
  1524.  
  1525.                 This command allows the user to download one or more files
  1526.                 from the system.
  1527.  
  1528.                 Maximus first prompts the user to select a file transfer
  1529.                 protocol. (However, if the user has selected a default file
  1530.                 transfer protocol from the Change Setup menu, Maximus will
  1531.                 automatically skip to the next step.)
  1532.  
  1533.                 Maximus includes internal support for Xmodem, Xmodem-1k,
  1534.                 Ymodem, Ymodem-G, SEAlink, and Zmodem. Other transfer pro-
  1535.                 tocols can be added as external protocols.
  1536.  
  1537.                 After selecting a protocol, users are prompted to enter the
  1538.                 names of the files to be downloaded, one file to a line.
  1539.                 Files that were previously tagged using the Tag command are
  1540.                 automatically included in the list.
  1541.  
  1542.  
  1543.  
  1544.              2. Maximus Overview                                        23
  1545.  
  1546.                 When processing filenames entered by the user, Maximus
  1547.                 automatically expands wildcards, including the "*" and "?"
  1548.                 characters.
  1549.  
  1550.                 In addition, if the FB utility is used to maintain a system
  1551.                 file database, the filenames entered by the user can reside
  1552.                 in any file area. (Otherwise, the user must change to the
  1553.                 correct file area before selecting the Download command.)
  1554.  
  1555.                 In addition to entering filenames, the user can also:
  1556.  
  1557.                 * press <enter> to start the download,
  1558.                 * enter /q to abort the transfer without sending any
  1559.                   files,
  1560.                 * enter /e to enter edit mode. This mode allows the user
  1561.                   to list and delete files in the download queue, or
  1562.                 * enter /g to start the download and automatically hang up
  1563.                   when the transfer is complete.
  1564.  
  1565.              Tag
  1566.  
  1567.                 This command allows the user to queue one or more files for
  1568.                 later download. The Tag command is also accessible through
  1569.                 the t command when performing a File Titles or Locate com-
  1570.                 mand.
  1571.  
  1572.                 To download files which have been tagged using this com-
  1573.                 mand, simply select the Download command and press <enter>
  1574.                 at the File(s) to download: prompt.
  1575.  
  1576.              Upload
  1577.  
  1578.                 This command allows the user to upload (send) files to the
  1579.                 system. If no default file transfer protocol is defined,
  1580.                 Maximus prompts the user for the protocol to be used for
  1581.                 the upload. If the user selects Xmodem or Xmodem-1K, Maxi-
  1582.                 mus also prompts the user for the name of the file to be
  1583.                 uploaded. (With all of the other file transfer protocols,
  1584.                 the filename is automatically transmitted by the sending
  1585.                 terminal program.)
  1586.  
  1587.                 Maximus will then start the upload. After the transfer is
  1588.                 complete, Maximus will prompt the user to enter a descrip-
  1589.                 tion for each file that is uploaded.
  1590.  
  1591.                 Maximus can use the upload filename to automatically screen
  1592.                 out certain types of uploads. The \max\badfiles.bbs file
  1593.                 contains a list of files to be ignored. This list of files
  1594.                 can include wildcards. A sample badfiles.bbs could look
  1595.                 like this:
  1596.  
  1597.                 MAKE$$$.TXT
  1598.                 MAKECASH.*
  1599.  
  1600.  
  1601.  
  1602.              2. Maximus Overview                                        24
  1603.  
  1604.                 *.RBS
  1605.                 *.GBS
  1606.                 *.BBS
  1607.                 *.GIF
  1608.                 *.JPG
  1609.                 *.TIF
  1610.  
  1611.              Statistics
  1612.  
  1613.                 This command displays the user's statistics, including the
  1614.                 amount of time that the user has been online for the cur-
  1615.                 rent call, the time online for the day, number of kilobytes
  1616.                 uploaded, number of kilobytes downloaded, and so on.
  1617.  
  1618.              Contents
  1619.  
  1620.                 This command displays the internal file catalog of a com-
  1621.                 pressed file. The Contents command can display the direc-
  1622.                 tory of any .zip, .arc, .pak, .arj or .lzh file
  1623.  
  1624.              Raw Directory
  1625.  
  1626.                 This command displays a listing of all files in the current
  1627.                 area, including files which are not listed in the files.bbs
  1628.                 catalog for that area. This command is normally only avail-
  1629.                 able to the SysOp.
  1630.  
  1631.              Override Path
  1632.  
  1633.                 This command allows the user to override the download path
  1634.                 for the current file area. For example, the download path
  1635.                 can be overridden to c:\max to allow a privileged user to
  1636.                 download files from the Maximus system directory. This com-
  1637.                 mand is normally only available to the SysOp.
  1638.  
  1639.              Hurl
  1640.  
  1641.                 This command moves a file from one area to another. Maximus
  1642.                 prompts the user for the name of the destination area and
  1643.                 the name of the file to be moved. This command is normally
  1644.                 only available to the SysOp.
  1645.  
  1646.              Kill File
  1647.  
  1648.                 This command deletes a file from the current file area.
  1649.                 Maximus will prompt the user for the name of the file to be
  1650.                 deleted. Maximus will ask the user to confirm the name of
  1651.                 the file to be deleted; if the user answers "n" to this
  1652.                 prompt, Maximus will give the user the option of leaving
  1653.                 the physical file alone and removing the entry from the
  1654.                 file listing. This command is normally only available to
  1655.                 the SysOp.
  1656.  
  1657.  
  1658.  
  1659.              2. Maximus Overview                                        25
  1660.  
  1661.              2.8. The Change Setup Menu
  1662.  
  1663.              This menu allows the user to modify settings in the user pro-
  1664.              file. The following commands are available on the standard
  1665.              Change Setup menu:
  1666.  
  1667.              City
  1668.  
  1669.                 This command modifies the user's "City" setting.
  1670.  
  1671.              Phone Number
  1672.  
  1673.                 This command modifies the user's "Phone Number" setting.
  1674.  
  1675.              Alias
  1676.  
  1677.                 This command is designed for use on systems that support
  1678.                 aliases. This command allows a user to change his/her
  1679.                 alias.
  1680.  
  1681.              Password
  1682.  
  1683.                 This command changes the user's password. The user is first
  1684.                 prompted to enter the old password. The user is given five
  1685.                 chances to correctly enter the old password before Maximus
  1686.                 hangs up.
  1687.  
  1688.                 Next, the user is prompted to enter the new password. The
  1689.                 user must enter the new password twice to prevent acciden-
  1690.                 tal typing errors.
  1691.  
  1692.              Help Level
  1693.  
  1694.                 This command selects the system help level. Maximus sup-
  1695.                 ports the help levels shown below in Table 2.2:
  1696.  
  1697.                 Table 2.2 System Help Levels
  1698.  
  1699.                 Type     Description
  1700.  
  1701.                 NOVICE   Full menus
  1702.                 REGULAR  Abbreviated menus
  1703.                 EXPERT   No menus
  1704.  
  1705.  
  1706.  
  1707.              Nulls
  1708.  
  1709.                 This command selects the number of NUL characters which are
  1710.                 transmitted after every line of text. Most users will not
  1711.                 need to use this command.
  1712.  
  1713.  
  1714.  
  1715.              2. Maximus Overview                                        26
  1716.  
  1717.              Width
  1718.  
  1719.                 This command changes the assumed screen width. This value
  1720.                 is used by Maximus when displaying system menus and when
  1721.                 drawing the full-screen editor display.
  1722.  
  1723.                 However, for local users, Maximus will automatically detect
  1724.                 the local screen size and adjust the "current width" value
  1725.                 accordingly. The local screen size value overrides (but
  1726.                 does not update) the value in the user file.
  1727.  
  1728.              Length
  1729.  
  1730.                 This command changes the assumed screen length.
  1731.  
  1732.              Tabs
  1733.  
  1734.                 This command toggles the translation of tab characters.
  1735.                 Maximus normally sends tab characters directly to the
  1736.                 user's terminal. However, if the user's terminal program
  1737.                 does not support tab characters, this option can be dis-
  1738.                 abled.
  1739.  
  1740.              More
  1741.  
  1742.                 This command toggles the "More [Y,n,=]?" prompts on and
  1743.                 off.
  1744.  
  1745.              Video Mode
  1746.  
  1747.                 This command selects the user's video mode. Maximus sup-
  1748.                 ports the following video modes:
  1749.  
  1750.                 * TTY
  1751.                 * ANSI
  1752.                 * AVATAR
  1753.  
  1754.                 RIPscrip graphics mode can be toggled by a separate menu
  1755.                 option.
  1756.  
  1757.              Full-Screen Editor
  1758.  
  1759.                 This command toggles the use of the MaxEd full-screen edi-
  1760.                 tor. If MaxEd is turned off, BORED is used for message ed-
  1761.                 iting.
  1762.  
  1763.              IBM Graphics
  1764.  
  1765.                 This command toggles the use of IBM "extended ASCII" char-
  1766.                 acters. DOS and OS/2 based computers support an "extended"
  1767.                 8-bit character set, including characters for box-drawing
  1768.                 and block graphics. Most non-IBM systems do not support
  1769.                 these extended ASCII characters, so Maximus can be config-
  1770.  
  1771.  
  1772.  
  1773.              2. Maximus Overview                                        27
  1774.  
  1775.                 ured to map extended ASCII characters into normal ASCII
  1776.                 characters.
  1777.  
  1778.              Hotkeys
  1779.  
  1780.                 This command toggles the hotkeys setting. Turning on hot-
  1781.                 keys instructs Maximus to process keystrokes as soon as
  1782.                 they are received (without requiring an <enter> after most
  1783.                 commands).
  1784.  
  1785.              Language
  1786.  
  1787.                 This command selects an alternate system language. Maximus
  1788.                 supports up to eight different language files, and the user
  1789.                 can switch between installed language files at any time.
  1790.  
  1791.              Protocol
  1792.  
  1793.                 This command selects a default file transfer protocol. When
  1794.                 a default protocol is selected, the Download command imme-
  1795.                 diately displays the File(s) to download: prompt instead of
  1796.                 asking the user to select a protocol.
  1797.  
  1798.              Archiver
  1799.  
  1800.                 This command selects a default archiving program. This al-
  1801.                 lows the user to select a commonly-used archiver for com-
  1802.                 pressing QWK mail packets.
  1803.  
  1804.              Show in Userlist
  1805.  
  1806.                 This command toggle's the displaying of the user's name in
  1807.                 the system user list. Users are displayed in the user list
  1808.                 by default, but this command can be used to hide the dis-
  1809.                 play of the user's name and last-call information.
  1810.  
  1811.              Full-Screen Reader
  1812.  
  1813.                 This command toggles the use of the full-screen reader
  1814.                 (FSR). When the FSR is enabled, Maximus will display a
  1815.                 stylized blue box at the top of the screen when reading
  1816.                 messages. This header includes information from the To,
  1817.                 From and Subject fields, information on the message reply
  1818.                 links, and net/node information.
  1819.  
  1820.              RIP
  1821.  
  1822.                 This command toggles the use of RIPscrip graphics. When
  1823.                 this command is selected, Maximus will test the remote
  1824.                 user's terminal program to ensure that it supports
  1825.                 RIPscrip. If RIPscrip graphics support is not detected,
  1826.                 Maximus will not enable RIPscrip graphics.
  1827.  
  1828.  
  1829.  
  1830.              2. Maximus Overview                                        28
  1831.  
  1832.              Quit
  1833.  
  1834.                 This command returns to the main menu.
  1835.  
  1836.  
  1837.              2.9. The SysOp Menu
  1838.  
  1839.              This menu contains commands that are normally only accessible
  1840.              to the SysOp.
  1841.  
  1842.              User Editor
  1843.  
  1844.                 This invokes the Maximus internal user editor. This command
  1845.                 is normally only available to the SysOp. Please see
  1846.                 Appendix E for more information.
  1847.  
  1848.              OS Shell
  1849.  
  1850.                 This command invokes either a local or a remote shell to
  1851.                 the operating system. Note that <alt-j> can always be used
  1852.                 from the local console to shell to the operating system.
  1853.  
  1854.         OS/2    When running external programs that are not specifically
  1855.        only!    designed to run as doors, OS/2 users should use the Max-
  1856.                 Pipe program to invoke the command, rather than redirect-
  1857.                 ing input with the "<" and ">" characters.
  1858.  
  1859.          DOS    Under DOS, if you are using an alternate command processor
  1860.        only!    (such as 4DOS or NDOS), the entry for this command (in the
  1861.                 menus control file) must be changed to reflect the name of
  1862.                 your command processor.
  1863.  
  1864.  
  1865.              2.10. The Chat Menu
  1866.  
  1867.              Maximus supports an internal multinode chat facility. Users
  1868.              on different nodes can hold private discussions with one an-
  1869.              other, and users can even engage in large group discussions
  1870.              on a "virtual CB channels."
  1871.  
  1872.              CB Chat
  1873.  
  1874.                 The CB Chat function allows two or more users to partici-
  1875.                 pate in a real-time multinode chat. Messages can be sent
  1876.                 back and forth to all users who are participating on a spe-
  1877.                 cific CB channel. Messages are sent to other users one line
  1878.                 at a time. Maximus supports up to 255 virtual CB channels.
  1879.  
  1880.              Page User
  1881.  
  1882.                 The Page User command allows a user to initiate a private
  1883.                 chat with another node. Selecting Page instructs Maximus to
  1884.                 send a "chat request" message to the specified node number.
  1885.  
  1886.  
  1887.  
  1888.              2. Maximus Overview                                        29
  1889.  
  1890.                 Maximus will then place the paging user in chat mode and
  1891.                 wait for the other user to respond to the page.
  1892.  
  1893.              Answer Page
  1894.  
  1895.                 The Answer Page command is used in conjunction with the
  1896.                 Page User command. After a user receives a page request
  1897.                 from another node, the paged user can select Answer Page to
  1898.                 engage in a private chat with the first user.
  1899.  
  1900.              Toggle Status
  1901.  
  1902.                 The Toggle Status command allows a user to toggle the chat
  1903.                 availability flag. Users who are unavailable for chat can-
  1904.                 not be paged using the Page User command.
  1905.  
  1906.  
  1907.              2.11. The Off-Line Reader Menu
  1908.  
  1909.              The Off-Line Reader menu is the key to Maximus's internal QWK
  1910.              mail packer. Commands on this menu can be used to select a
  1911.              default protocol and archiving program, select a set of mes-
  1912.              sage areas, download messages from that set of areas, and up-
  1913.              load reply packets.
  1914.  
  1915.              Tag Area
  1916.  
  1917.                 The Tag Area command (equivalent to the command of the same
  1918.                 name on the message menu) allows the user to select a set
  1919.                 of message areas to be processed by the Browse and Download
  1920.                 commands.
  1921.  
  1922.              Download New Messages
  1923.  
  1924.                 The Download command packs all new messages in the user's
  1925.                 set of tagged areas. The messages are then compressed into
  1926.                 an archive and sent to the user.
  1927.  
  1928.              Upload Replies
  1929.  
  1930.                 The Upload Replies command allows the user to upload a .rep
  1931.                 reply packet. Max automatically determines the program used
  1932.                 to compress the .rep file, decompresses the reply packet,
  1933.                 and places the uploaded messages into the appropriate ar-
  1934.                 eas.
  1935.  
  1936.              Protocol Default
  1937.  
  1938.                 The Protocol Default command allows the user to select a
  1939.                 default file transfer protocol.
  1940.  
  1941.  
  1942.  
  1943.              2. Maximus Overview                                        30
  1944.  
  1945.              Archiver Default
  1946.  
  1947.                 The Archiver Default command allows the user to select a
  1948.                 default archiving program.
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.                                                             3. Installation
  1958.  
  1959.              This section of describes how to install a new copy of Maxi-
  1960.              mus 3.0. (To upgrade from Maximus 2.0, simply run the install
  1961.              program and follow the directions.)
  1962.  
  1963.  
  1964.              3.1. Step 1: Unpacking the Distribution Files
  1965.  
  1966.              If you purchased a copy of Maximus, all of the required files
  1967.              are on the distribution disk and nothing more needs to be
  1968.              done. Skip to step 2 for information on running the install
  1969.              program.
  1970.  
  1971.              Otherwise, if you obtained Maximus electronically, the system
  1972.              consists of three separate archives, as shown below in Table
  1973.              3.1:
  1974.  
  1975.              Table 3.1 Maximus Distribution Files
  1976.  
  1977.               File          Description
  1978.  
  1979.               max300r.zip   DOS (real-mode) executables.
  1980.               max300p.zip   OS/2 (protected-mode) executables.
  1981.               max300c.zip   Common executables and files for both DOS and
  1982.                             OS/2.
  1983.  
  1984.  
  1985.  
  1986.              To install Maximus, you need max300c.zip, plus either or both
  1987.              of max300r.zip or max300p.zip, depending on the operating
  1988.              systems that you wish to use.
  1989.  
  1990.              The install program will examine the files that are avail-
  1991.              able, and if both the DOS and OS/2 versions of the executa-
  1992.              bles are present, it will allow you to select either or both
  1993.              versions for installation. Of course, you can also install
  1994.              Maximus for only one of the supported operating systems.
  1995.  
  1996.              The first step in the installation is to unarchive all of the
  1997.              required .zip files into a temporary subdirectory. (The in-
  1998.              stall program will move the files from the temporary direc-
  1999.              tory to a permanent directory of your choice, so this tempo-
  2000.              rary directory can be located anywhere on your system.)
  2001.  
  2002.              To decompress the .zip files, you need either the commercial
  2003.              "PKUNZIP" program from PKWare or the freeware "unzip" program
  2004.              from InfoZip.
  2005.  
  2006.              The following files are contained inside the .zip archives:
  2007.  
  2008.  
  2009.  
  2010.              3. Installation                                            32
  2011.  
  2012.              *  an ASCII version of the system documentation,
  2013.              *  the install program,
  2014.              *  the program license agreement, and
  2015.              *  a number of files with a .fiz extension. Most of the pro-
  2016.                 grams in the distribution kit are packed using the proprie-
  2017.                 tary FIZ compression algorithm, and the only way to extract
  2018.                 these files is to run the install program.
  2019.  
  2020.  
  2021.              3.2. Step 2: Running the Installation Program
  2022.  
  2023.              To execute the install program, run install.exe from the in-
  2024.              stall disk (or from the temporary directory, for the elec-
  2025.              tronic distribution version).
  2026.  
  2027.              After displaying some copyright information, the install pro-
  2028.              gram will prompt you for the type of install to perform. Se-
  2029.              lect the New Install button here, since these installation
  2030.              instructions only describe new installations.
  2031.  
  2032.              In the next dialog box, the install program will prompt you
  2033.              for a number of system paths. Aside from changing the drive
  2034.              letter or root name of the \max directory hierarchy, inexpe-
  2035.              rienced users should leave these paths alone.
  2036.  
  2037.              Next, the install program will prompt you for some basic in-
  2038.              formation about your system, including the BBS name, the name
  2039.              of the SysOp, and information about your communications hard-
  2040.              ware.
  2041.  
  2042.              In the dialog box, simply type text in the appropriate boxes,
  2043.              and use <tab> (or click with the mouse) to move between
  2044.              fields. To select a particular option from a radio button
  2045.              group, use the <left> and <right> keys to cursor over to the
  2046.              appropriate location and press <space> to select that option.
  2047.              Press <enter> or click on the OK button when you have speci-
  2048.              fied the correct values.
  2049.  
  2050.         OS/2 Most of the executables in the OS/2 version of Maximus end
  2051.        only! with the letter "p." This "p" signifies that the executable
  2052.              runs in protected mode and is a native OS/2 application. Add-
  2053.              ing an extra "p" to the filename allows both Maximus-DOS and
  2054.              Maximus-OS/2 to be installed into the same directory.
  2055.  
  2056.              However, to keep this manual concise, only the base name of
  2057.              an executable is mentioned, without the trailing "p." When
  2058.              working through the installation, keep in mind that when the
  2059.              documentation refers to an executable filename, a "p" should
  2060.              be added for OS/2 users.
  2061.  
  2062.              For example, while the DOS version of the "ANS2BBS" utility
  2063.              is called ans2bbs.exe, the OS/2 version is called
  2064.              ans2bbsp.exe.
  2065.  
  2066.  
  2067.  
  2068.              3. Installation                                            33
  2069.  
  2070.              3.3. Step 3: Configuring your Modem
  2071.  
  2072.              This section describes how to configure your modem to work
  2073.              with Maximus and other related software packages.
  2074.  
  2075.              The modem is your BBS's gateway to the rest of the world, but
  2076.              it can also be one of the most difficult components to con-
  2077.              figure correctly. Due to the wide variety of modem manufac-
  2078.              turers and products, this manual cannot possibly cover all
  2079.              aspects of installing and configuring modems. However, this
  2080.              documentation describes a common set of modem commands that
  2081.              are supported by most popular modems.
  2082.  
  2083.              To run smoothly, Maximus requires a Hayes-compatible modem.
  2084.              Although it may be possible to use Maximus with a non Hayes-
  2085.              compatible modem, only Hayes-compatible modems are officially
  2086.              supported.
  2087.  
  2088.              When setting up your modem, the first step is to determine
  2089.              how your modem handles the Data Carrier Detect (DCD) signal.
  2090.              DCD is a signal sent by the modem to your computer to indi-
  2091.              cate when a connection has been established.
  2092.  
  2093.              When your modem is idle, DCD is normally in the low state.
  2094.              However, as soon as a user connects to your modem, DCD be-
  2095.              comes high. Maximus uses the DCD signal to determine when a
  2096.              user connects with the system, and it also uses DCD to deter-
  2097.              mine when a caller hangs up.
  2098.  
  2099.              Unfortunately, the default settings of many lower-speed mo-
  2100.              dems instruct the modem to always set the DCD signal high,
  2101.              regardless of whether or not the connection is active.
  2102.  
  2103.              To ensure that your modem is reporting the DCD signal prop-
  2104.              erly, you must check the configuration of your modem. Depend-
  2105.              ing on your modem type, this can be done in a number of ways:
  2106.  
  2107.              1200 bps modems. If your modem is 1200 bps or slower, chances
  2108.              are that your modem's DCD handling is controlled by DIP
  2109.              switches. DIP switches are the small plastic toggles on the
  2110.              front, rear or bottom of your modem. (One or more panels may
  2111.              need to be removed to access these switches.)
  2112.  
  2113.              On most 1200 bps modems, DIP switch #6 controls the DCD sig-
  2114.              nal. For proper operation, this switch should be in the up
  2115.              position so that the modem reports the true DCD value.
  2116.              (However, some modems are different, so please consult your
  2117.              modem documentation before changing any DIP switches.)
  2118.  
  2119.              In addition, you may also need to change one of the other DIP
  2120.              switches so that your modem sends back verbal result codes
  2121.              (as opposed to numbers). The DIP switch to control these re-
  2122.              sult codes is manufacturer-dependent, so you will again need
  2123.  
  2124.  
  2125.  
  2126.              3. Installation                                            34
  2127.  
  2128.              to consult your modem's manual to determine which switch to
  2129.              check.
  2130.  
  2131.              2400 bps, 9600 bps, 14.4 kbps, 19.2 kbps, or 28.8 kbps. If
  2132.              your modem is 2400 bps or faster, the configuration process
  2133.              can usually be performed using a standard terminal program
  2134.              (including Procomm Plus, Telix, Crosstalk, and others).
  2135.  
  2136.              After loading your terminal program and configuring it for
  2137.              the correct communications port, type in the command "AT" and
  2138.              press <enter>. If everything is well, your modem should re-
  2139.              turn an "OK" response.
  2140.  
  2141.              After you have established that your modem is working cor-
  2142.              rectly, enter the command "AT&C1&S1&D2&W" and press <enter>.
  2143.              (If this command does not work, try omitting either or both
  2144.              of the "&C1" or the "&S1" strings, since some modems do not
  2145.              support these settings.) This command configures your modem
  2146.              so that DCD always reflects the modem's actual state, and it
  2147.              also configures your modem's DTR handling so that Maximus can
  2148.              use the DTR signal to end a session and hang up on a user.
  2149.  
  2150.              External modems. If you have an external modem, one other po-
  2151.              tential problem is the modem cable. If your cable does not
  2152.              have the correct signals wired through, your modem may still
  2153.              behave as if DCD is set incorrectly, regardless of DIP switch
  2154.              settings.
  2155.  
  2156.              The best way to determine whether or not your modem cable is
  2157.              working correctly is simply to borrow a cable from another
  2158.              SysOp with a working BBS and try it on your system.
  2159.  
  2160.              If you determine that your cable is at fault, most computer
  2161.              stores or service centers can order or manufacture a modem
  2162.              cable. The wiring specifications for modem cables are:
  2163.  
  2164.              DB25 connectors (25 pins). This is the most common type of
  2165.              modem cable. As a minimum, pins 2 through 8 and pin 20 must
  2166.              be wired straight through.
  2167.  
  2168.              DB9 connectors (9 pins). All nine pins must be wired straight
  2169.              through.
  2170.  
  2171.  
  2172.              3.4. Step 4: Installing Communications Drivers
  2173.  
  2174.  
  2175.              3.4.1. OS/2 Communications Drivers
  2176.  
  2177.         OS/2 The following paragraphs are for OS/2 users only. DOS users
  2178.        only! can skip to section 3.4.2.
  2179.  
  2180.  
  2181.  
  2182.              3. Installation                                            35
  2183.  
  2184.              Unlike DOS, OS/2 does not require a FOSSIL driver. OS/2 in-
  2185.              cludes its own device driver to handle serial I/O. Unfortu-
  2186.              nately, the device driver included with OS/2 does not work
  2187.              correctly in all situations. (Under OS/2 2.x, the supplied
  2188.              COM.SYS driver sometimes uninstalls itself after certain com-
  2189.              munication errors occur.)
  2190.  
  2191.              Fortunately, a number of third-party device drivers are
  2192.              available:
  2193.  
  2194.              The 16-bit COM16550.SYS device driver can be used instead of
  2195.              the standard IBM driver. An evaluation version of COM16550 is
  2196.              bundled with Maximus, but COM16550 is a third-party product
  2197.              that is not sold or supported by Lanius. Please see the docu-
  2198.              mentation in the \max\com16550.zip file for more information.
  2199.  
  2200.              In addition, a third-party, 32-bit device driver called
  2201.              SIO.SYS has many more features than COM16550 and can operate
  2202.              at much higher speeds. SIO.SYS is not provided with Maximus,
  2203.              but it can be obtained from the Hobbes OS/2 archive at
  2204.              ftp.cdrom.com. SIO can also be found on most bulletin board
  2205.              systems that offer OS/2 support.
  2206.  
  2207.              Please note that COM16550 has a maximum speed of 19.2 kbps,
  2208.              whereas SIO.SYS has a maximum speed of 57.6 kbps. For this
  2209.              reason, if you are running a V.34 or V.FC modem, SIO.SYS is
  2210.              preferable to COM16550.
  2211.  
  2212.              In addition, Maximus runs with any serial device driver that
  2213.              supports the standard OS/2 "ASYNC IOCtl" interface. This
  2214.              means that Maximus-OS/2 can be used with intelligent serial
  2215.              cards such as the DigiBoard or the ARCTIC card.
  2216.  
  2217.  
  2218.              3.4.2. DOS FOSSIL Drivers
  2219.  
  2220.              Under DOS, Maximus requires an external serial port driver
  2221.              called a FOSSIL. FOSSIL is an acronym which stands for
  2222.              "Fido/Opus/SEAdog Standard Interface Layer." The FOSSIL han-
  2223.              dles all of Maximus's low-level serial communication needs,
  2224.              including sending and receiving characters.
  2225.  
  2226.              Using a FOSSIL allows Maximus to be used on a wide range of
  2227.              serial port hardware without modifying the Maximus core. (For
  2228.              example, third-party vendors have developed FOSSIL drivers
  2229.              that support the DigiBoard intelligent serial card.)
  2230.  
  2231.              Maximus ships with a copy of Unique Computing Pty's BNU FOS-
  2232.              SIL driver. BNU supports most non-intelligent serial ports.
  2233.              If BNU is not suitable or will not run on your system, other
  2234.              FOSSIL drivers are available. Some of the most common FOSSILs
  2235.              are X00 and OpusComm.
  2236.  
  2237.  
  2238.  
  2239.              3. Installation                                            36
  2240.  
  2241.              There are two separate types of FOSSIL drivers. Some FOSSIL
  2242.              drivers, such as OpusComm and BNU, are loaded as Terminate
  2243.              and Stay Resident (TSR) programs in the c:\autoexec.bat file.
  2244.              Other drivers, including X00, are loaded in the c:\config.sys
  2245.              file. Although different FOSSIL drivers have different set-up
  2246.              instructions, it is fairly easy to install a FOSSIL for a ba-
  2247.              sic configuration.
  2248.  
  2249.              OpusComm installation. To install OpusComm on COM1, simply
  2250.              insert the following commands at the beginning of your AUTO-
  2251.              EXEC.BAT:
  2252.  
  2253.                 opuscomm
  2254.                 ocom_cfg L1=19200     (see note below!)
  2255.  
  2256.              Ensure that opuscomm.com and ocom_cfg.exe are on your current
  2257.              PATH, or else these commands will not work.
  2258.  
  2259.              The second "ocom_cfg" line locks port 1 at a speed of 19200
  2260.              bps. This line is required for 9600+ bps modems. (Note that
  2261.              OpusComm does not support speeds faster than 19.2kbps.)
  2262.  
  2263.              This line is only required if you are using a 9600+ bps mo-
  2264.              dem. Users with 2400 bps or slower modems must not include
  2265.              the call to ocom_cfg.
  2266.  
  2267.              BNU installation. To install BNUcom on COM1, simply insert
  2268.              the following command at the beginning of your AUTOEXEC.BAT:
  2269.  
  2270.                 bnu -l0=38400
  2271.  
  2272.              Ensure that bnu.com is on your current PATH, or else this
  2273.              command will not work.
  2274.  
  2275.              The "-l0=38400" command instructs BNU to lock port 0 (COM1)
  2276.              at a speed of 38.4 kbps. This parameter is required for 9600+
  2277.              bps modems. Users with 2400 bps modems must omit the
  2278.              "-l0=38400" parameter.
  2279.  
  2280.        Warni BNU uses 0-based COM port numbers. To lock the speed of COM1,
  2281.          ng! use "-l0=speed"; to lock the speed of COM2, use "-l1=speed";
  2282.              and so on.
  2283.  
  2284.              X00 installation. To install the X00 driver on COM1, simply
  2285.              insert the following command at the beginning of your CON-
  2286.              FIG.SYS:
  2287.  
  2288.                 DEVICE=X00.SYS B,0,19200
  2289.  
  2290.              Ensure that X00.SYS is in your c:\ directory, or else this
  2291.              command will not work.
  2292.  
  2293.  
  2294.  
  2295.              3. Installation                                            37
  2296.  
  2297.              The "B,0,19200" parameter instructs X00 to lock COM1 at a
  2298.              speed of 19200 bps. This parameter is required for 9600+ bps
  2299.              modems. Users with 2400 bps modems must omit the "B,0,19200"
  2300.              parameter.
  2301.  
  2302.        Warni X00 uses 0-based COM port numbers. To lock the speed of COM1,
  2303.          ng! use "B,0,speed"; to lock the speed of COM2, use "B,1,speed";
  2304.              and so on.
  2305.  
  2306.  
  2307.              3.4.3. Checklist for high-speed modems
  2308.  
  2309.              When using a high speed modem (9600 bps or above, including
  2310.              any modems which support V.32, V.32bis, V.32ter, V.FC, or
  2311.              V.34), the modem normally communicates with the host BBS at a
  2312.              fixed speed, regardless of the speed of the user's modem. For
  2313.              this reason, if you are running a high-speed modem, you must
  2314.              instruct Maximus to talk to the modem at a fixed speed.
  2315.  
  2316.              To use a fixed port speed, you must:
  2317.  
  2318.              *  ensure that the "&B1" parameter is included in your modem
  2319.                 initialization string,
  2320.  
  2321.              *  ensure that CTS flow control is enabled (using the "Mask
  2322.                 Handshaking CTS" option in the system control files), and
  2323.  
  2324.              *  use the -sspeed command line parameter when starting Maxi-
  2325.                 mus. (This parameter is only required when running Maximus
  2326.                 in a mode that handles remote callers. This parameter is
  2327.                 not required when starting Maximus in local mode.)
  2328.  
  2329.                 For example, to instruct Maximus to wait for a caller and
  2330.                 use a locked port rate of 38.4 kbps:
  2331.  
  2332.                 max -s38400 -w
  2333.  
  2334.                 The "-s38400" parameter instructs Maximus to talk to the
  2335.                 serial port at 38.4 kbps only. The modem itself will handle
  2336.                 all rate negotiation with the remote system.
  2337.  
  2338.  
  2339.              3.5. Step 5: Editing Configuration Files
  2340.  
  2341.              In order to run Maximus on your system, you need to make sev-
  2342.              eral changes to your system configuration files, including
  2343.              config.sys and autoexec.bat.
  2344.  
  2345.              For example, Maximus and related utilities always need to
  2346.              know how to find the main Maximus system directory. To accom-
  2347.              plish this, these utilities examine the system environment
  2348.              for the MAXIMUS environment variable. This variable must al-
  2349.              ways point to the master system configuration file.
  2350.  
  2351.  
  2352.  
  2353.              3. Installation                                            38
  2354.  
  2355.         OS/2 DOS users should skip the next few paragraphs.
  2356.        only!
  2357.              To set up the Maximus environment variable under OS/2, you
  2358.              must add the following line to the end of the config.sys file
  2359.              on your OS/2 boot drive:
  2360.  
  2361.                 SET MAXIMUS=C:\MAX\MAX.PRM
  2362.  
  2363.              This example assumes that Maximus was installed in the c:\max
  2364.              directory. If you installed Maximus somewhere else, substi-
  2365.              tute the appropriate path for "c:\max".
  2366.  
  2367.              After making this change to config.sys, you must reboot the
  2368.              computer for the change to take effect.
  2369.  
  2370.          DOS OS/2 users should skip to the next section.
  2371.        only!
  2372.              To configure Maximus to run under DOS, you must add a number
  2373.              of lines to your c:\config.sys file. An ASCII editor, such as
  2374.              the standard DOS edit.com, can be used to edit this file.
  2375.  
  2376.              The first line to be added to config.sys is the "buffers="
  2377.              statement. If there is no BUFFERS line in your config.sys
  2378.              file, simply add the following line to the end of the file:
  2379.  
  2380.                 BUFFERS=30
  2381.  
  2382.              However, if a BUFFERS line already exists, ensure that it
  2383.              specifies a value of at least 30.
  2384.  
  2385.              Next, the "files=" statement must be added. If there is no
  2386.              FILES line in your config.sys file, simply add the following
  2387.              line to the end of the file:
  2388.  
  2389.                 FILES=40
  2390.  
  2391.              However, if a FILES line already exists, ensure that it
  2392.              specifies a value of at least 40.
  2393.  
  2394.              Finally, if you plan to use Maximus in a multinode environ-
  2395.              ment, Maximus also requires the share.exe program. (Even in
  2396.              single-node environments, share.exe is still strongly recom-
  2397.              mended.)
  2398.  
  2399.              To install share.exe, simply add the following line to the
  2400.              end of c:\autoexec.bat:
  2401.  
  2402.                 share
  2403.  
  2404.              Note for Novell users. Installing share.exe is not completely
  2405.              necessary. As long as you load int2f.com after running the
  2406.              Netware shell, you do not need to load share.exe.
  2407.  
  2408.  
  2409.  
  2410.              3. Installation                                            39
  2411.  
  2412.              Note for Windows for Workgroups and Windows 95 users. Windows
  2413.              comes with a SHARE-compatible VxD, and as long as you run
  2414.              Maximus exclusively within the Windows for Workgroups or Win-
  2415.              dows 95 environments, you do not need to install share.exe.
  2416.  
  2417.              Finally, to set up the system environment variable under DOS,
  2418.              you must add the following line to the end of the
  2419.              c:\autoexec.bat file:
  2420.  
  2421.                 SET MAXIMUS=C:\MAX\MAX.PRM
  2422.  
  2423.              This example assumes that Maximus was installed in the c:\max
  2424.              directory. If you installed Maximus somewhere else, substi-
  2425.              tute the appropriate path for "c:\max".
  2426.  
  2427.              Once you have made all of these changes and saved the con-
  2428.              figuration files, you should press <ctrl-alt-del> to reboot
  2429.              the computer. Unless you reboot now, changes made to con-
  2430.              fig.sys and autoexec.bat will not take effect.
  2431.  
  2432.  
  2433.              3.6. Step 6: About Control Files
  2434.  
  2435.              This is the most complicated step in setting up a Maximus
  2436.              system. Four text-based configuration files control most of
  2437.              the operations of your system: max.ctl, msgarea.ctl,
  2438.              filearea.ctl and menus.ctl.
  2439.  
  2440.              max.ctl controls almost everything about your system, from
  2441.              the name of the log-on display file to the "time reward"
  2442.              given to users who upload files.
  2443.  
  2444.              msgarea.ctl controls all of the message areas that are acces-
  2445.              sible to users.
  2446.  
  2447.              filearea.ctl controls all of the file areas that are accessi-
  2448.              ble to users.
  2449.  
  2450.              menus.ctl controls all of the menus and options that can be
  2451.              selected by users.
  2452.  
  2453.              All of these text files are stored in an ASCII format, so the
  2454.              DOS edit.com or the OS/2 e.exe can be used to modify these
  2455.              files.
  2456.  
  2457.              These files contain a number of fairly complicated commands,
  2458.              but these control files give you control over even the most
  2459.              minute aspects of your BBS. However, the power to tailor your
  2460.              BBS to a very specific set of needs also makes it relatively
  2461.              easy to configure your system incorrectly. Consequently, new
  2462.              SysOps are advised to refrain from making too many modifica-
  2463.              tions to the control files until the basic BBS is up and run-
  2464.              ning.
  2465.  
  2466.  
  2467.  
  2468.              3. Installation                                            40
  2469.  
  2470.              The installation program will have already customized most of
  2471.              the system control files, so no specific modifications are
  2472.              required at this point.
  2473.  
  2474.  
  2475.              3.7. Step 7: Compiling the Control Files
  2476.  
  2477.              Every time you modify max.ctl or any of the other control
  2478.              files, you must run SILT, the Maximus control file compiler.
  2479.              If you make changes to your control files and forget to run
  2480.              SILT, Maximus will not recognize the changes that you have
  2481.              made.
  2482.  
  2483.        Note! The system installation program will have already compiled
  2484.              your control file for the first time. However, it is a good
  2485.              idea to compile it again here, just so that you can learn how
  2486.              to run SILT..
  2487.  
  2488.              Compiling your control files with SILT is easy; just enter
  2489.              the following from the command prompt:
  2490.  
  2491.                 silt ctlname
  2492.  
  2493.              where ctlname is the name of your main system control file.
  2494.              In the default installation, the main control file is always
  2495.              called max, so most users only need to type "silt max".
  2496.  
  2497.              When SILT runs, it automatically compiles all of the control
  2498.              files, including menus.ctl, filearea.ctl, msgarea.ctl, and a
  2499.              number of other control files. These secondary control files
  2500.              cannot be compiled alone; you must always run SILT on the
  2501.              main control file, regardless of which secondary control file
  2502.              was changed.
  2503.  
  2504.              When SILT runs, it will scan through all of the control files
  2505.              and write a compiled version of the system information to
  2506.              max.prm, marea.dat, farea.dat, and a number of other system
  2507.              data files.
  2508.  
  2509.              If you made mistakes in the control files, such as misspell-
  2510.              ing a keyword or omitting a parameter, SILT will warn you
  2511.              about these mistakes. To correct these problems, use either
  2512.              the DOS edit.com or the OS/2 e.exe to load the control file,
  2513.              move to the problem line number, fix the error, and then re-
  2514.              compile using SILT.
  2515.  
  2516.  
  2517.              3.8. Step 8: Starting Maximus
  2518.  
  2519.              Once you have compiled your control files, you are finally
  2520.              ready to start Maximus. Although your BBS is still fairly ge-
  2521.              neric, it is now usable.
  2522.  
  2523.  
  2524.  
  2525.              3. Installation                                            41
  2526.  
  2527.              To start up Maximus for the first time, enter the following
  2528.              sequence of commands. This example assumes that you have in-
  2529.              stalled Maximus in the c:\max directory:
  2530.  
  2531.                 c:
  2532.                 cd \max
  2533.                 max -c
  2534.  
  2535.              The "-c" parameter tells Maximus to create a new user file,
  2536.              so you should only do this the first time you run Maximus.
  2537.              However, if you are converting from another BBS program, you
  2538.              should run the CVTUSR program before entering the above com-
  2539.              mand. (See section 8.3 for more information on the CVTUSR
  2540.              program.)
  2541.  
  2542.        Warni By default, Maximus encrypts all passwords in the Maximus
  2543.          ng! user file. While this adds an extra layer of security to your
  2544.              system, it means that you will be unable to convert your
  2545.              Maximus user file to the file format of any other BBS pro-
  2546.              gram. If you want to disable the password encryption, see the
  2547.              No Password Encryption feature in the system control file.)
  2548.  
  2549.              After entering "max -c", Maximus will display a copyright
  2550.              banner and print out a warning about the lack of an existing
  2551.              user file. Maximus will then display the prompt: "Your Name
  2552.              Here [Y,n]?", where "Your Name Here" is the name entered in
  2553.              the "SysOp" box in the installation program. Type the letter
  2554.              "Y" to continue your logon.
  2555.  
  2556.              After doing this, Maximus will display some text that de-
  2557.              scribes your BBS. This text is contained in the
  2558.              \max\misc\applic.mec file. (Files with an extension of .mec
  2559.              will be discussed in greater detail later in this document.)
  2560.  
  2561.              Maximus will also prompt you for a few pieces of information,
  2562.              including your city, phone number, and password. Maximus will
  2563.              also prompt you for ANSI screen control support, the MaxEd
  2564.              editor, IBM-PC characters, hotkeys, and RIPscrip graphics
  2565.              support. Answer "y" to the first four prompts, but answer "n"
  2566.              to the RIPscrip graphics question.
  2567.  
  2568.              After Maximus has finished configuring your account, it will
  2569.              display a welcome screen and a bulletin file. Finally, it
  2570.              will place you at the main system menu. All of the screens
  2571.              that you see are completely customizable. The steps required
  2572.              to customize these files are described later in this manual.
  2573.  
  2574.              Now that Maximus is working, you will probably want to look
  2575.              around for a while. Feel free to explore the different fea-
  2576.              tures of your new BBS. If you want to send some test NetMail
  2577.              messages, try going into the user editor (from the SysOp
  2578.              menu) and giving yourself some NetMail credit.
  2579.  
  2580.  
  2581.  
  2582.              3. Installation                                            42
  2583.  
  2584.              When you have finished looking around at your new BBS, type
  2585.              "g" from any menu to log off, and Maximus will exit back to
  2586.              the command prompt.
  2587.  
  2588.  
  2589.              3.9. Step 9: Support for Remote Callers
  2590.  
  2591.              To handle non-local callers, Maximus must be run from a batch
  2592.              file. Unlike local log-ins, Maximus requires a batch file to
  2593.              recycle after remote callers.
  2594.  
  2595.              There are two mutually-exclusive methods of running Maximus:
  2596.  
  2597.              *  Max can be run using the internal Waiting For Caller (WFC)
  2598.                 subsystem. WFC takes care of answering the phone and talk-
  2599.                 ing to the modem, so no external programs are required.
  2600.  
  2601.              *  Maximus can also be run under a front end. A front end
  2602.                 takes care of answering the phone and performing additional
  2603.                 processing. Front ends are normally only required for Fi-
  2604.                 doNet or UUCP support. If you are running a standalone sys-
  2605.                 tem, you do not require a front end.
  2606.  
  2607.              In some cases, systems that run multiple nodes may wish to
  2608.              run a front end only on a subset of the BBS lines. In many
  2609.              cases, only one node needs to run a front end program, while
  2610.              the others can all use the internal WFC module. The command
  2611.              line is used to configure the system for WFC or front end op-
  2612.              eration, so no changes to the control files are required to
  2613.              support this.
  2614.  
  2615.  
  2616.              3.9.1. Running the MODE command
  2617.  
  2618.         OS/2 If you are running Maximus under OS/2, special care must be
  2619.        only! taken to set up the communications port before calling Maxi-
  2620.              mus. In most cases, the OS/2 MODE command is used to config-
  2621.              ure the port. MODE is used to set the port speed, flow con-
  2622.              trol characteristics, and buffer settings.
  2623.  
  2624.              In most cases, the following command should be issued before
  2625.              trying to run Maximus with a remote caller. This command must
  2626.              be entered all on one line without spaces:
  2627.  
  2628.                 MODE COMport:speed,n,8,1,,TO=OFF,XON=ON,
  2629.                   IDSR=OFF,ODSR=OFF,OCTS=ON,DTR=ON,RTS=HS
  2630.  
  2631.              In the above command, port is the 1-based com port number of
  2632.              your Maximus system. speed is the maximum communications rate
  2633.              supported by your modem. This line should be included in the
  2634.              command file that starts Maximus.
  2635.  
  2636.  
  2637.  
  2638.              3. Installation                                            43
  2639.  
  2640.              For example, to configure com port 1 for 38.4 kbps, the fol-
  2641.              lowing command should be used:
  2642.  
  2643.                 MODE COM1:38400,n,8,1,,TO=OFF,XON=ON,IDSR=OFF,
  2644.                   ODSR=OFF,OCTS=ON,DTR=ON,RTS=HS
  2645.  
  2646.              If your modem has special flow control requirements, please
  2647.              see the documentation for the MODE command for more informa-
  2648.              tion. (On-line help is available by typing "help mode" from
  2649.              the OS/2 command prompt.)
  2650.  
  2651.  
  2652.              3.9.2. Using WFC Mode
  2653.  
  2654.              When run in this mode, Maximus handles incoming callers on
  2655.              its own. The first step in enabling WFC mode is to use the
  2656.              "-w" command line parameter. To start Maximus in the most ba-
  2657.              sic WFC mode, the following command is used:
  2658.  
  2659.                 max -w
  2660.  
  2661.              "-w" instructs Maximus to enter WFC mode. After this command
  2662.              is executed, Maximus will load up, display a few windows,
  2663.              initialize the modem, and then wait for an incoming call.
  2664.              Maximus will automatically detect the incoming caller's speed
  2665.              and switch speeds automatically.
  2666.  
  2667.              By default, Maximus is set up to run on any Hayes-compatible
  2668.              modem. If the WFC subsystem does not seem to be answering the
  2669.              phone correctly, read through the comments in the Equipment
  2670.              section of the system control file. Some of the modem command
  2671.              strings may need to be modified, but almost all modems can be
  2672.              made to work with Maximus.
  2673.  
  2674.              In addition to the standard "-w" switch, you can also use the
  2675.              "-b" (baud rate) and "-p" (COM port) switches to specify an
  2676.              alternate port number and maximum baud rate for the current
  2677.              node, overriding the defaults in the control file.
  2678.  
  2679.              For example, to start WFC on port 2 with a baud rate of
  2680.              38400, specify the following command:
  2681.  
  2682.                 max -w -p2 -b38400
  2683.  
  2684.              To run WFC mode with a high-speed modem (9600+ bps), you must
  2685.              use a locked COM port. The "-s" command line parameter tells
  2686.              Maximus the speed to use for locking the port.
  2687.  
  2688.              For example, the following command is used to run Maximus
  2689.              with a high-speed modem on COM2 (locked at 38.4 kbps):
  2690.  
  2691.                 max -w -p2 -s38400
  2692.  
  2693.  
  2694.  
  2695.              3. Installation                                            44
  2696.  
  2697.              No matter which options you use, the command line must always
  2698.              include a "-w" if you wish to handle remote callers. This
  2699.              command must be placed in the batch or command file that
  2700.              starts Maximus. (The batch/command file is described in more
  2701.              detail later in this section.)
  2702.  
  2703.              The WFC module can also handle timed events which cause Maxi-
  2704.              mus to wake up on specific days of the week or at a specific
  2705.              time of day. Please see section 5.1 for more information on
  2706.              WFC mode.
  2707.  
  2708.  
  2709.              3.9.3. Using an External Front End
  2710.  
  2711.              In this mode, Maximus will not answer the telephone by it-
  2712.              self. You must obtain a third-party "front end" or "mailer"
  2713.              program to handle incoming calls. There are at least a dozen
  2714.              freeware/shareware FidoNet front ends for DOS, and two or
  2715.              three similar programs for OS/2. (At the time of this writ-
  2716.              ing, the two most common front ends were BinkleyTerm and
  2717.              FrontDoor.)
  2718.  
  2719.              Although setting up your front-end mailer is beyond the scope
  2720.              of this document, you will find several sample batch files
  2721.              for different front end mailers in Appendix G.
  2722.  
  2723.              Your mailer's documentation may give some specific instruc-
  2724.              tions for interfacing it with a Maximus system; if so, you
  2725.              should just follow those directions. If not, read on.
  2726.  
  2727.              When Maximus starts up with a caller already on-line, it ex-
  2728.              pects to be given a minimum of one parameter: "-bspeed",
  2729.              where speed is the speed of the caller.
  2730.  
  2731.              Generally, these parameters are passed from the mailer via
  2732.              the spawnbbs.bat or exebbs.bat files.
  2733.  
  2734.         OS/2 Under OS/2, Maximus also expects to be passed the COM port
  2735.        only! handle from the calling program. This means that the minimum
  2736.              requirements for starting Maximus are:
  2737.  
  2738.                 maxp -bspeed -phandle
  2739.  
  2740.              where speed is the speed of the caller and handle is the OS/2
  2741.              file handle for the communications port. Unlike under DOS,
  2742.              the -p parameter is a COM port handle (which is not the same
  2743.              value as the COM port number). This means that this value
  2744.              must be passed to Maximus by your front end mailer.
  2745.  
  2746.  
  2747.  
  2748.              3. Installation                                            45
  2749.  
  2750.              3.9.4. Maximus Errorlevels
  2751.  
  2752.              Although the preceding commands allow Maximus to handle one
  2753.              remote caller, either through the WFC subsystem or through a
  2754.              front end program, Maximus normally exits back to the command
  2755.              prompt after it processes a caller.
  2756.  
  2757.              After Maximus terminates, it needs to tell your system what
  2758.              to do next. For example, if a user entered a message in an
  2759.              EchoMail area, you may want to use an external utility (such
  2760.              as Squish) to export that message, or you may wish to run
  2761.              some sort of logging utility.
  2762.  
  2763.              To provide for these external programs, Maximus tells the op-
  2764.              erating system to set a numeric value called an errorlevel.
  2765.              As mentioned earlier, Maximus supports several different er-
  2766.              rorlevels for various types of events, including users enter-
  2767.              ing EchoMail messages, users entering NetMail messages, log-
  2768.              ging off before the user enters a name, and so on.
  2769.  
  2770.              In several places throughout the control files, you can in-
  2771.              struct Maximus to use a certain errorlevel when a given event
  2772.              occurs. Errorlevels are always numeric, and they always have
  2773.              a value from 1 to 255. In most cases, the errorlevels values
  2774.              do not need to be modified, but you can change them if you
  2775.              must. (However, Maximus reserves errorlevels 1 through 4 to
  2776.              indicate errors, so you should not use these values in the
  2777.              control file.)
  2778.  
  2779.              Once Maximus is set up to use errorlevels, you must also
  2780.              write a batch file to detect the errorlevel returned by Maxi-
  2781.              mus and take the appropriate action.
  2782.  
  2783.              The following statement is used to test an errorlevel in a
  2784.              .bat file (DOS) or in a .cmd file (OS/2):
  2785.  
  2786.                 if errorlevel erl action
  2787.  
  2788.              erl is a number which corresponds to the errorlevel value for
  2789.              the event, as specified in the system control file.
  2790.  
  2791.              action is an action that is to be performed when the speci-
  2792.              fied errorlevel is detected. This action can consist of any
  2793.              normal batch file statement.
  2794.  
  2795.              However, if you wish to test for multiple errorlevels, be
  2796.              warned that both DOS and OS/2 examine errorlevels using a
  2797.              greater-than-or-equal-to comparison. This means that the fol-
  2798.              lowing statement:
  2799.  
  2800.                 if errorlevel 10 echo Hi!
  2801.  
  2802.  
  2803.  
  2804.              3. Installation                                            46
  2805.  
  2806.              will be executed if Maximus sets an errorlevel value of 10 or
  2807.              greater.
  2808.  
  2809.              For this reason, if you have more than one errorlevel to
  2810.              process, the group of errorlevel statements must be listed in
  2811.              descending order. For example, to check for errorlevels 1, 3,
  2812.              9, 10, 11 and 12, your batch file would look like this:
  2813.  
  2814.                 max -w -p1 -b38400
  2815.  
  2816.                 if errorlevel 12 echo Do operation "A" here.
  2817.                 if errorlevel 11 echo Do operation "B" here.
  2818.                 if errorlevel 10 echo Do operation "C" here.
  2819.                 if errorlevel  9 echo Do operation "D" here.
  2820.                 if errorlevel  3 echo Do operation "E" here.
  2821.                 if errorlevel  1 echo Do operation "F" here.
  2822.  
  2823.              Also, remember that all programs modify the errorlevel value
  2824.              when they are run. In the example given above, if you wanted
  2825.              to run a program called abcd.exe when errorlevel 12 was en-
  2826.              countered, the abcd.exe program would change the errorlevel
  2827.              to a new value after abcd terminated. Since the batch file is
  2828.              executed one line at a time, the following errorlevel checks
  2829.              (from 11 through 1) would be testing the errorlevel set by
  2830.              abcd.exe, not the errorlevel set by Maximus!
  2831.  
  2832.              To work around this limitation, you must use the goto state-
  2833.              ment for each errorlevel check. The goto statement allows
  2834.              your batch file to jump to a completely different location
  2835.              within the same batch file when a certain errorlevel is en-
  2836.              countered. An errorlevel-based goto statement looks like
  2837.              this:
  2838.  
  2839.                 if errorlevel erl goto label
  2840.  
  2841.              As before, erl is the errorlevel value to be tested.
  2842.  
  2843.              The label value is a unique, alphanumeric, single-word name
  2844.              that indicates the destination of the jump. (Examples of
  2845.              valid label names are "GotCaller," "DidScanBld" and
  2846.              "Recycle.")
  2847.  
  2848.              In English, the above statement reads:
  2849.  
  2850.                 If the errorlevel value is greater or equal to the value
  2851.                 specified by erl, jump to the label in the batch/command
  2852.                 file specified by label.
  2853.  
  2854.              To specify the destination of the jump, you must declare the
  2855.              label by placing the same name at another point in the same
  2856.              batch file. This lets the operating system know where it
  2857.              should jump to when it encounters the goto statement.
  2858.  
  2859.  
  2860.  
  2861.              3. Installation                                            47
  2862.  
  2863.              A label declaration looks like this:
  2864.  
  2865.                 :label
  2866.  
  2867.              label is the same label name that was specified in the origi-
  2868.              nal goto statement. As soon as the command processor spots a
  2869.              statement of the form "goto label," it will jump to the loca-
  2870.              tion marked with ":label".
  2871.  
  2872.              For example, the following sample batch file:
  2873.  
  2874.                 Line 1: :Top
  2875.                 Line 2: echo Diamonds are forever
  2876.                 Line 3: goto Top
  2877.  
  2878.              causes the line "Diamonds are forever" to be repeated over
  2879.              and over on the screen.
  2880.  
  2881.              When the operating system starts the batch file, it processes
  2882.              each line in sequence. After reading line 1, the OS recog-
  2883.              nizes that "Top" is simply a label definition, so it skips to
  2884.              the next line.
  2885.  
  2886.              After reading line 2, it processes the echo statement and
  2887.              displays "Diamonds are forever."
  2888.  
  2889.              Finally, after reading line 3, it realizes that it has to
  2890.              jump to the label marked "Top." Since the "Top" label is at
  2891.              the top of the file, it goes back to line 1 and repeats the
  2892.              entire process over and over again.
  2893.  
  2894.              However, the goto statement does have practical applications.
  2895.              The previous Maximus errorlevel example could be rewritten
  2896.              like this:
  2897.  
  2898.                 max -w -p1 -b38400
  2899.                 if errorlevel 12 goto OpA
  2900.                 if errorlevel 11 goto OpB
  2901.                 if errorlevel 10 goto OpC
  2902.                 if errorlevel  9 goto OpD
  2903.                 if errorlevel  3 goto OpE
  2904.                 if errorlevel  1 goto OpF
  2905.  
  2906.                 :OpA
  2907.                 echo Do operation "A" here.
  2908.                 goto End
  2909.  
  2910.                 :OpB
  2911.                 echo Do operation "B" here.
  2912.                 goto End
  2913.  
  2914.                 :OpC
  2915.                 echo Do operation "C" here.
  2916.  
  2917.  
  2918.  
  2919.              3. Installation                                            48
  2920.  
  2921.                 goto End
  2922.  
  2923.                 :OpD
  2924.                 echo Do operation "D" here.
  2925.                 goto End
  2926.  
  2927.                 :OpE
  2928.                 echo Do operation "E" here.
  2929.                 goto End
  2930.  
  2931.                 :OpF
  2932.                 echo Do operation "F" here.
  2933.                 goto End
  2934.  
  2935.                 :End
  2936.  
  2937.              In this situation, the OS first compares the errorlevel re-
  2938.              turned by Maximus to those listed in the "if errorlevel" por-
  2939.              tion of the batch file. When it finds a match for the error-
  2940.              level, it jumps to the corresponding label.
  2941.  
  2942.              For example, if Maximus exited using errorlevel 10, the batch
  2943.              file interpreter would jump down to the "OpC" label and proc-
  2944.              ess the "echo Do operation `C' here" statement. (Most of the
  2945.              time, you would run an actual program after checking for an
  2946.              errorlevel, rather than simply echoing a string back to the
  2947.              console.)
  2948.  
  2949.              After processing the echo statement, the command processor
  2950.              reads and processes the next line of the batch file. The
  2951.              "goto End" statement ensures that the command processor skips
  2952.              over the following commands after the "OpD" label definition.
  2953.              (Recall that the command processor simply ignores label defi-
  2954.              nitions. Without the extra "goto End," the batch file would
  2955.              just "fall through" to the statements under the OpD and OpE
  2956.              labels. The extra goto statement specifically instructs the
  2957.              command processor to jump to the "End" label at the end of
  2958.              the file.)
  2959.  
  2960.              However, it may also be desirable to have the batch file
  2961.              "fall through" a set of errorlevels in certain cases. This
  2962.              allows errorlevels to be defined such that a certain error-
  2963.              level value, such as the "user entering EchoMail" value, also
  2964.              executes the command associated with another errorlevel
  2965.              value, such as the "user entered NetMail" value.
  2966.  
  2967.  
  2968.              3.9.5. Sample WFC Batch File
  2969.  
  2970.              Maximus uses errorlevels 1 through 4 for internal purposes,
  2971.              but errorlevel values of 5 and greater can be configured by
  2972.              the user. A standard Maximus installation uses the following
  2973.              errorlevel values:
  2974.  
  2975.  
  2976.  
  2977.              3. Installation                                            49
  2978.  
  2979.              Errorlevel 255. Maximus terminated with an undefined error
  2980.              condition. Your batch file should return to your front-end
  2981.              mailer or restart Maximus in WFC mode.
  2982.  
  2983.              Errorlevel 12. A user entered EchoMail (and possibly also
  2984.              NetMail) during this session. In response, your batch file
  2985.              should call an external program to export mail to the net-
  2986.              work. If you are using the Squish mail processor, this com-
  2987.              mand should be "squish in out squash". In addition, if you
  2988.              use any *.MSG format message areas, you must also call
  2989.              SCANBLD at this point. Finally, after calling all of these
  2990.              external programs, your batch file should return to your
  2991.              mailer or restart Maximus in WFC mode.
  2992.  
  2993.              Errorlevel 11. A user entered NetMail (but no EchoMail) dur-
  2994.              ing this session. In response, your batch file should call
  2995.              your mail packer to export mail to the network. If you are
  2996.              using the Squish mail processor, this command should be
  2997.              "squish squash". In addition, if you use any *.MSG format
  2998.              message areas, you must also call SCANBLD at this point. Fi-
  2999.              nally, after calling all of these external programs, your
  3000.              batch file should return to your mailer or restart Maximus in
  3001.              WFC mode.
  3002.  
  3003.              Errorlevel 5. A user logged off and entered neither EchoMail
  3004.              nor NetMail. If you use any *.MSG format message areas, you
  3005.              must call SCANBLD at this point. Your batch file should then
  3006.              return to your mailer or restart Maximus in WFC mode.
  3007.  
  3008.              Errorlevels 4 and 3. A non-fatal error occurred. Your batch
  3009.              file should return to your mailer (or restart Maximus in WFC
  3010.              mode) if either of these errorlevels are detected.
  3011.  
  3012.              Errorlevel 2. The caller hung up before entering a valid name
  3013.              at the log-on prompt. Your batch file should return to your
  3014.              mailer or restart Maximus in WFC mode.
  3015.  
  3016.              Errorlevel 1. The SysOp pressed <alt-x> at the main WFC
  3017.              screen. Your batch file should exit back to the operating
  3018.              system.
  3019.  
  3020.              The following runbbs.bat (or runbbs.cmd for OS/2) can be used
  3021.              to start Maximus in WFC mode and accept callers:
  3022.  
  3023.                 @echo off
  3024.          DOS    rem * DOS users only:
  3025.        only!    rem *
  3026.                 rem * This line loads your FOSSIL driver.
  3027.  
  3028.                 bnu
  3029.  
  3030.  
  3031.  
  3032.              3. Installation                                            50
  3033.  
  3034.         OS/2    rem * OS/2 users only:
  3035.        only!    rem *
  3036.                 rem * Comment out the above call to BNU
  3037.                 rem * and uncomment the following MODE command.
  3038.                 rem *(This command should be all be on one line.)
  3039.                 rem *
  3040.                 rem * mode com1:19200,n,8,1,TO=OFF,XON=ON,
  3041.                 rem *   IDSR=OFF,ODSR=OFF,OCTS=ON,DTR=ON,RTS=HS
  3042.  
  3043.  
  3044.                 :Loop
  3045.                 max -w -p1 -b19200
  3046.                 if errorlevel 255 goto Error
  3047.                 if errorlevel  16 goto Error
  3048.                 if errorlevel  12 goto EchoMail
  3049.                 if errorlevel  11 goto NetMail
  3050.                 if errorlevel   5 goto Aftercall
  3051.                 if errorlevel   4 goto Error
  3052.                 if errorlevel   3 goto Error
  3053.                 if errorlevel   2 goto Loop
  3054.                 if errorlevel   1 goto Done
  3055.  
  3056.  
  3057.                 :EchoMail
  3058.                 rem * Invoke scanner and packer here. Next,
  3059.                 rem * go to the "Aftercall" label to process
  3060.                 rem * any after-caller actions.
  3061.                 rem *
  3062.                 rem * For the Squish mail processor, use the
  3063.                 rem * following command:
  3064.                 rem
  3065.                 rem SQUISH OUT SQUASH -fc:\max\echotoss.log
  3066.  
  3067.                 goto Aftercall
  3068.  
  3069.  
  3070.  
  3071.                 :NetMail
  3072.                 rem * Invoke packer here, then go to
  3073.                 rem * the "Aftercall" label.
  3074.                 rem
  3075.                 rem For the Squish mail processor, use the
  3076.                 rem following command:
  3077.                 rem
  3078.                 rem SQUISH SQUASH
  3079.  
  3080.                 goto Aftercall
  3081.  
  3082.  
  3083.  
  3084.                 :Aftercall
  3085.                 rem * Invoke after-each-caller utilities here.
  3086.                 scanbld all
  3087.  
  3088.  
  3089.  
  3090.              3. Installation                                            51
  3091.  
  3092.                 goto End
  3093.  
  3094.  
  3095.                 :Error
  3096.                 rem * Something bad happened, so let's say so.
  3097.  
  3098.                 echo An error occurred!
  3099.                 goto Down
  3100.  
  3101.                 :End
  3102.                 rem * This label should re-load your phone
  3103.                 rem * answering program. If you are using
  3104.                 rem * the Maximus WFC, you want to jump back
  3105.                 rem * to the top of the loop:
  3106.  
  3107.                 goto Loop
  3108.  
  3109.                 :Down
  3110.  
  3111.                 rem * The system arrives here if there was a
  3112.                 rem * problem.
  3113.  
  3114.                 echo Error! Maximus had a fatal error and
  3115.                 echo could not continue!
  3116.  
  3117.                 :Done
  3118.                 exit
  3119.  
  3120.              To start Maximus, simply run the above runbbs.bat from the
  3121.              command prompt. Maximus will initialize and accept as many
  3122.              incoming connections as required.
  3123.  
  3124.              For sample batch files that demonstrate how to use Maximus
  3125.              with a front-end mailer, please see Appendix G.
  3126.  
  3127.  
  3128.              3.10. Step 10: Miscellaneous Information
  3129.  
  3130.              You have now completed the installation procedure for Maxi-
  3131.              mus. Although Maximus is now mostly installed, please keep
  3132.              these things in mind:
  3133.  
  3134.              For users of *.MSG areas. A renumbering utility is required.
  3135.              If you carry any EchoMail areas with a lot of traffic, a re-
  3136.              numbering utility will be especially crucial. Maximus is bun-
  3137.              dled with the MR program. MR automatically deletes, renumbers
  3138.              and links messages based on information given in the message
  3139.              area control file. For more information on MR, please see
  3140.              section 8.9.
  3141.  
  3142.              For users of Squish areas. Although Squish normally renumbers
  3143.              areas messages are created, you may occasionally need to use
  3144.              the SQPACK utility. SQPACK compacts message area data files
  3145.  
  3146.  
  3147.  
  3148.              3. Installation                                            52
  3149.  
  3150.              by removing unused space between messages. Most systems will
  3151.              only need to run SQPACK once a week, but it may be beneficial
  3152.              to run SQPACK on a daily basis for systems with a lot of
  3153.              traffic. SQPACK is part of the Squish product, the companion
  3154.              mail processor for Maximus. The Squish product also includes
  3155.              a number of other useful utilities, including a diagnostic
  3156.              and repair utility for Squish areas.
  3157.  
  3158.              Your Maximus system should now be capable of handling call-
  3159.              ers, but many other options and features can be customized.
  3160.              The following section describes how to maintain some of the
  3161.              major components in a Maximus system.
  3162.  
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.                                                            4. Customization
  3171.  
  3172.              This section describes how to customize the main components
  3173.              of a Maximus system. This section is just an overview of the
  3174.              possible customizations. For a full list of features and/or
  3175.              control file keywords, please see section 18.
  3176.  
  3177.  
  3178.              4.1. Events and Yelling
  3179.  
  3180.              The distribution copy of Maximus comes with a preconfigured
  3181.              event file. This event file serves two purposes:
  3182.  
  3183.              *  With the internal WFC subsystem, the event file is used to
  3184.                 schedule "external events." External events are used for
  3185.                 running external programs at predefined times. These events
  3186.                 are useful for performing daily system maintenance, general
  3187.                 cleanup, and anything else you may require.
  3188.  
  3189.              *  The event file also controls yell events. Yell events are
  3190.                 used to define the times of the day when callers are al-
  3191.                 lowed to page the SysOp. A yell event also controls how
  3192.                 many times the SysOp can be paged and the tune to be played
  3193.                 during the page.
  3194.  
  3195.              All events are kept in the file called events##.bbs, where ##
  3196.              is the node number of the task (in hexadecimal). For a sin-
  3197.              gle-line system, ## will be "01".
  3198.  
  3199.              Each node on a multinode system must have a separate events
  3200.              file. However, all of the event files use the same format, so
  3201.              you can simply copy a master events file to events01.bbs,
  3202.              events02.bbs, and so on. (If Maximus cannot find the event
  3203.              file for a specific node, it will try to read default event
  3204.              information from events00.bbs, regardless of the node number
  3205.              of the current session.)
  3206.  
  3207.  
  3208.              4.1.1. Yell Events
  3209.  
  3210.              The distribution version of Maximus comes with an event file
  3211.              called events00.bbs. The standard event file contains a sin-
  3212.              gle yell event that looks like this:
  3213.  
  3214.                 Event All  13:00 23:00 bells=3 maxyell=3 tune=random
  3215.  
  3216.              This yell event is active between 13:00 and 23:00. (This
  3217.              means that the user is allowed to page the SysOp between 1 pm
  3218.              and 11 pm.)
  3219.  
  3220.  
  3221.  
  3222.              4. Customization                                           54
  3223.  
  3224.              If desired, additional yelling time slots can be added by
  3225.              simply duplicating the "Event" line and changing the starting
  3226.              and ending times.
  3227.  
  3228.              The bells flag indicates the number of times that the bell or
  3229.              tune will be played.
  3230.  
  3231.              The maxyell flag indicates that a user is allowed to yell up
  3232.              to three times during one session before the SysOp page fea-
  3233.              ture is automatically disabled. (If the SysOp enters chat
  3234.              with the user, the yell count for that session is reset.)
  3235.  
  3236.              Finally, the tune flag indicates the tune to be played during
  3237.              the page. Maximus includes a large library of tunes in the
  3238.              \max\tunes.bbs file. Specifying "tune=random" instructs Maxi-
  3239.              mus to play a tune at random. However, you can also specify
  3240.              an explicit tune name, such as "tune=DigitalPhone".
  3241.  
  3242.  
  3243.              4.1.2. External Events
  3244.  
  3245.              The event file also supports external events. An external
  3246.              event causes Maximus to exit with an errorlevel at a prede-
  3247.              fined time of day or on a certain day of the week. Events are
  3248.              only active when Maximus is started in WFC mode.
  3249.  
  3250.              To add an external event, simply add a line to events##.bbs
  3251.              with the appropriate starting time, and add an "exit=level"
  3252.              flag to the end of the line.
  3253.  
  3254.              level specifies the errorlevel that Maximus will exit with
  3255.              when the event time occurs.
  3256.  
  3257.              After creating an entry for the event in the events##.bbs
  3258.              file, you should modify your runbbs.bat file to handle the
  3259.              specified errorlevel and run the appropriate external com-
  3260.              mand.
  3261.  
  3262.              Please see section 18.11 for more information on the events
  3263.              file.
  3264.  
  3265.  
  3266.              4.1.3. SoundBlaster Support
  3267.  
  3268.         OS/2 This section applies only to OS/2 users.
  3269.        only!
  3270.              Maximus-OS/2 includes internal support for the SoundBlaster
  3271.              and SoundBlaster-compatible sound cards.
  3272.  
  3273.              When playing yell tunes, Maximus will automatically determine
  3274.              whether or not a SoundBlaster is installed. If a SoundBlaster
  3275.              is found, Maximus will play the tunes from tunes.bbs on the
  3276.  
  3277.  
  3278.  
  3279.              4. Customization                                           55
  3280.  
  3281.              SoundBlaster, rather than making noises on the internal PC
  3282.              speaker.
  3283.  
  3284.              However, the SoundBlaster detection is not completely auto-
  3285.              matic. You must include the following line in your config.sys
  3286.              file to enable SoundBlaster support:
  3287.  
  3288.                 SET OS2BLASTER=Abase Iirq Ddma NOCLI
  3289.  
  3290.              where base is the card's base address, irq is the card's IRQ
  3291.              level, and dma is the card's DMA channel. The "NOCLI" parame-
  3292.              ter must be included literally. This parameter tells the
  3293.              SoundBlaster code not to steal the CPU for long periods of
  3294.              time.
  3295.  
  3296.              Except for the last "NOCLI" flag, the OS2BLASTER settings are
  3297.              identical to the settings for the standard DOS "BLASTER" en-
  3298.              vironment variable.
  3299.  
  3300.              The settings for a standard SoundBlaster card are:
  3301.  
  3302.                 SET OS2BLASTER=A220 I7 D1 NOCLI
  3303.  
  3304.  
  3305.              4.2. Access Control: Classes, Privilege Levels and Locks
  3306.  
  3307.              This section describes the access control and security mecha-
  3308.              nisms supported by Maximus 3.0.
  3309.  
  3310.  
  3311.              4.2.1. User Classes
  3312.  
  3313.              Maximus uses the class concept to control access to menu op-
  3314.              tions, message areas, and other system components. A class
  3315.              describes the access rights and privileges of a group of us-
  3316.              ers. The distribution version of Maximus includes 12 prede-
  3317.              fined user classes, but additional classes can be defined by
  3318.              the SysOp.
  3319.  
  3320.              A class definition typically includes the following attrib-
  3321.              utes (among many others):
  3322.  
  3323.              *  maximum time limit,
  3324.              *  maximum number of calls per day,
  3325.              *  maximum daily download limit,
  3326.              *  file download:upload ratio,
  3327.              *  the name of a special display file to be shown at log-on,
  3328.                 and
  3329.              *  special system settings, such as the ability to write mes-
  3330.                 sages in read-only areas, unlimited on-line time, the abil-
  3331.                 ity to download any file on the system, and more.
  3332.  
  3333.  
  3334.  
  3335.              4. Customization                                           56
  3336.  
  3337.              (A complete list of class attributes can be found in section
  3338.              18.9.)
  3339.  
  3340.              In addition, classes are associated with specific privilege
  3341.              levels. A privilege level is a numeric value from 0 to 65535.
  3342.              The privilege level is generally proportional to the level of
  3343.              access granted to users in that class.
  3344.  
  3345.              To make classes easier to manage, Maximus also assigns a name
  3346.              to each class. You can refer to classes either by name or by
  3347.              privilege level.
  3348.  
  3349.              The classes included in the distribution version of Maximus
  3350.              are listed below in Table 4.1:
  3351.  
  3352.              Table 4.1 Standard Privilege Levels
  3353.  
  3354.               Class Name  Privilege Level
  3355.  
  3356.               Hidden           65535
  3357.               SysOp            100
  3358.               AsstSysOp        90
  3359.               Clerk            80
  3360.               Extra            70
  3361.               Favored          60
  3362.               Privil           50
  3363.               Worthy           40
  3364.               Normal           30
  3365.               Limited          20
  3366.               Demoted          10
  3367.               Transient        0
  3368.  
  3369.  
  3370.              The class names and privilege levels are completely configur-
  3371.              able, so if desired, the above names can be changed to re-
  3372.              flect the different types of users on your system.
  3373.  
  3374.  
  3375.              4.2.2. Privilege Levels
  3376.  
  3377.              In the system user file, Maximus assigns a specific privilege
  3378.              level to each user. Since Maximus stores only the numeric
  3379.              privilege level, this means that you are free to rename a
  3380.              class or change its attributes at any time. (The privilege
  3381.              level assigned to new users is controlled by the Logon Level
  3382.              feature in the system control file.)
  3383.  
  3384.              When a user logs on, Maximus compares the user's privilege
  3385.              level to the level of all defined user classes. Maximus then
  3386.              selects the class with the privilege level that is closest to
  3387.              (but not over) the user's privilege level.
  3388.  
  3389.  
  3390.  
  3391.              4. Customization                                           57
  3392.  
  3393.              For example, assume that a user is assigned a privilege level
  3394.              of 20. When the user logs on, Maximus will scan the class
  3395.              definitions and notice that the "Demoted" class has a privi-
  3396.              lege level of 20. This is an exact match of the user's privi-
  3397.              lege level, so Maximus will treat the user as a member of the
  3398.              Demoted class. The user will inherit all of the characteris-
  3399.              tics of the class, including the associated time and file
  3400.              download limits.
  3401.  
  3402.              By separating the access limits from the user record, it be-
  3403.              comes easy to adjust the permissions for a broad group of us-
  3404.              ers by modifying a single class definition. Since the user
  3405.              record stores only the class's privilege level, you can eas-
  3406.              ily rename the class (or replace it with another one) without
  3407.              modifying the user file.
  3408.  
  3409.              In addition, a user's privilege level does not need to ex-
  3410.              actly match one of the class privilege levels. Assume that a
  3411.              user is assigned a privilege level of 45. Maximus will select
  3412.              the user class with the level that is closest to (but which
  3413.              does not exceed) the user's privilege level. Given these cri-
  3414.              teria, Maximus will select the "Worthy" class (which has a
  3415.              privilege level of 40).
  3416.  
  3417.              Although the user's privilege level is slightly higher than
  3418.              the Worthy privilege level, the user is still considered to
  3419.              be a member of the Worthy class. The user assumes the same
  3420.              access restrictions (including time limits and download lim-
  3421.              its) as all other members of the Worthy class.
  3422.  
  3423.              From this, we see that all possible privilege levels (from 0
  3424.              to 65535) can be converted into a specific user class. If a
  3425.              class's privilege level is defined to be x, and if the privi-
  3426.              lege level of the next-highest class is defined to be y, all
  3427.              privilege levels in the range x to y - 1 (inclusive) are con-
  3428.              sidered to be part of the first class.
  3429.  
  3430.              This means that a user class actually encompasses a range of
  3431.              privilege levels. Assuming the standard class definitions
  3432.              given above, the standard privilege levels fall into the
  3433.              classes shown in Table 4.2:
  3434.  
  3435.              Table 4.2 Privilege Level Ranges
  3436.  
  3437.               Class Name   Privilege Range
  3438.  
  3439.               Hidden       65535
  3440.               SysOp         100-65534
  3441.               AsstSysOp      90-   99
  3442.               Clerk          80-   89
  3443.               Extra          70-   79
  3444.               Favored        60-   69
  3445.               Privil         50-   59
  3446.  
  3447.  
  3448.  
  3449.              4. Customization                                           58
  3450.  
  3451.               Worthy         40-   49
  3452.               Normal         30-   39
  3453.               Limited        20-   29
  3454.               Demoted        10-   19
  3455.               Transient       0-    9
  3456.  
  3457.  
  3458.              Now, since all users in a given class are granted the same
  3459.              access rights, you may wonder why Maximus allows multiple
  3460.              privilege levels to be assigned to a class. The answer lies
  3461.              in how Maximus processes access control definitions for com-
  3462.              mands and menu options: the access level for a menu command
  3463.              can be defined in terms of a class or in terms of a specific
  3464.              numeric privilege level.
  3465.  
  3466.              For example, although all members of the Worthy class (levels
  3467.              40 through 49) have the same time limit and download restric-
  3468.              tions, the SysOp can define a menu option that requires a
  3469.              privilege level of 46, which means that only some of the mem-
  3470.              bers of the Worthy class will be able to access the option.
  3471.  
  3472.              From this, one can see that the 12 standard user classes can
  3473.              be logically subdivided into many more individual access lev-
  3474.              els. And should the original 12 classes not be enough to fit
  3475.              your needs, more classes can be added as necessary.
  3476.  
  3477.              In situations where Maximus needs to display a user's privi-
  3478.              lege level, such as on the status line at the bottom of the
  3479.              screen, Maximus will first examine the class records to see
  3480.              if the user's privilege level is an exact match for one of
  3481.              the classes. If so, Maximus will display the class name. Oth-
  3482.              erwise, if Maximus cannot find an exact match, it will dis-
  3483.              play the numeric privilege level.
  3484.  
  3485.  
  3486.              4.2.3. SysOp and Hidden Attributes
  3487.  
  3488.              Of the 12 classes defined by Maximus, only two classes have
  3489.              extraordinary attributes:
  3490.  
  3491.              Users in the SysOp class have access to all system features
  3492.              and functions, including the ability to read private mes-
  3493.              sages, modify users in the system user editor, and examine
  3494.              any file on the local hard drive.
  3495.  
  3496.              Users in the Hidden class have no access to the system what-
  3497.              soever. If a user's privilege level is changed so that it
  3498.              falls into the Hidden class, Maximus will immediately hang up
  3499.              when the user calls. A user can be placed into the Hidden
  3500.              class to lock that user out of the system.
  3501.  
  3502.  
  3503.  
  3504.              4. Customization                                           59
  3505.  
  3506.              In addition, menu options can be assigned an access level of
  3507.              Hidden. A "Hidden" menu option cannot be accessed by any user
  3508.              on the system, regardless of the user's privilege level.
  3509.  
  3510.              Aside from the Hidden and SysOp classes, most of the other
  3511.              classes have only minor variations in time and download lim-
  3512.              its, so those classes can be assigned to normal users.
  3513.  
  3514.  
  3515.              4.2.4. Locks and Keys
  3516.  
  3517.              In addition to the user classes and privilege levels de-
  3518.              scribed above, Maximus supports a set of keys that can be as-
  3519.              signed to each user. A key is equivalent to a "yes/no" flag
  3520.              that can be turned on or off on a user-by-user basis.
  3521.  
  3522.              Maximus supports a total of 32 keys. Keys are referenced by a
  3523.              single letter or number. The 32 keys consist of the letters A
  3524.              through X and the numbers 1 through 8. Any or all of these
  3525.              keys can be assigned to users on an individual basis.
  3526.  
  3527.              Keys are independent of a user's privilege level or class.
  3528.              For example, a user with a privilege level of 20 (in the
  3529.              "Limited" class) could have keys 1, 3, D and L. A user with a
  3530.              privilege level of 15 (in the "Demoted" class) could have
  3531.              keys 3, 4, A and L.
  3532.  
  3533.              Keys are useful when some commands or menu options are only
  3534.              made available to a certain subset of users, regardless of
  3535.              privilege level. To restrict access to an system feature, the
  3536.              SysOp can "lock" the feature using a certain key or set of
  3537.              keys.
  3538.  
  3539.              For example, a company BBS could have several different file
  3540.              areas dedicated to different products. Owners of a certain
  3541.              product could be given key A, while owners of a different
  3542.              product could be given key B. The file areas could be re-
  3543.              stricted so that a user needs key A to access information re-
  3544.              lated to the first type of product, while the other file area
  3545.              could be restricted to those with key B. If a user happened
  3546.              to own both products, the user could be given both keys A and
  3547.              B to permit access to both types of areas.
  3548.  
  3549.              Similarly, an area could be restricted to users with keys A,
  3550.              B and C, such that only users who owned all three types of
  3551.              products would be able to access the area.
  3552.  
  3553.              Keys are also independent of a user's privilege level, so you
  3554.              can still assign different time and download limits to dif-
  3555.              ferent classes of users, regardless of which keys are as-
  3556.              signed to each user.
  3557.  
  3558.  
  3559.  
  3560.              4. Customization                                           60
  3561.  
  3562.              4.2.5. Access Control Strings
  3563.  
  3564.              Maximus uses an Access Control String (ACS) to describe the
  3565.              access requirements for menu options, message and file areas,
  3566.              and various other system components. An ACS can restrict a
  3567.              certain feature based on a user's class, privilege level, key
  3568.              settings, and numerous other attributes.
  3569.  
  3570.              The simplest form of an ACS is simply a privilege level or
  3571.              the name of a user class. For example, if a specific menu op-
  3572.              tion is assigned an ACS of:
  3573.  
  3574.                 46
  3575.  
  3576.              then only users with a privilege level of 46 or above would
  3577.              be able to access that option.
  3578.  
  3579.              Similarly, if you list the name of a user class, Maximus will
  3580.              convert the class name into a privilege level and compare it
  3581.              against the user's privilege level. For example, if a spe-
  3582.              cific menu option is assigned this ACS:
  3583.  
  3584.                 Privil
  3585.  
  3586.              then only users with a privilege level of 50 or above would
  3587.              be able to access that option. (This example assumes that
  3588.              your class definitions assign a privilege level of 50 to the
  3589.              "Privil" class.)
  3590.  
  3591.              In addition to the names of the defined user classes, an ACS
  3592.              of NoAccess indicates that access is not granted to any user.
  3593.              The NoAccess string may be useful if you have removed the
  3594.              "Hidden" user class.
  3595.  
  3596.              An ACS can also be used to ensure that only users with a cer-
  3597.              tain set of keys are allowed to access an option. To add a
  3598.              key restriction, simply append a "/" to the end of the privi-
  3599.              lege level or class name, and then list the keys that the
  3600.              user must possess to access the command.
  3601.  
  3602.              For example, this ACS restricts a command to users who have a
  3603.              privilege level of at least 55 and who have keys 2, 3, 5 and
  3604.              A:
  3605.  
  3606.                 50/235A
  3607.  
  3608.              The name of a user class can also be used anywhere that a
  3609.              privilege level definition can be used, so the above ACS
  3610.              could be restated as:
  3611.  
  3612.                 Normal/235A
  3613.  
  3614.  
  3615.  
  3616.              4. Customization                                           61
  3617.  
  3618.              An ACS can also restrict a command to users who do not have a
  3619.              certain set of keys. To add such a restriction, simply insert
  3620.              a "!" in front of the key that you wish to negate. For exam-
  3621.              ple, the following ACS:
  3622.  
  3623.                 Worthy/23!6A!C
  3624.  
  3625.              restricts a command to users who:
  3626.  
  3627.              *  have a privilege level of at least 40 (assuming the stan-
  3628.                 dard class definitions),
  3629.              *  have keys 2, 3 and A, and
  3630.              *  have neither key 6 nor key C.
  3631.  
  3632.              All of the above ACS examples have restricted a feature to
  3633.              users with a privilege level that was greater than or equal
  3634.              to a certain value. An ACS can also restrict a command to us-
  3635.              ers with an exact privilege level, or perform other types of
  3636.              logical tests.
  3637.  
  3638.              To add a logical test to an ACS, insert one of the operators
  3639.              shown below in Table 4.3:
  3640.  
  3641.              Table 4.3 Access Control String Operators
  3642.  
  3643.               Operator  Description
  3644.  
  3645.               =         Grants access if the user's privilege level is
  3646.                         exactly the specified level.
  3647.               >         Grants access if the user's privilege level is
  3648.                         strictly greater than the specified level.
  3649.               <         Grants access if the user's privilege level is
  3650.                         strictly less than the specified level.
  3651.               >=        Grants access if the user's privilege level is
  3652.                         greater than or equal to the specified level
  3653.                         (default).
  3654.               <=        Grants access if the user's privilege level is
  3655.                         less than or equal to the specified level.
  3656.               <> or !=  Grants access if the user's privilege level is
  3657.                         not equal to the specified level.
  3658.  
  3659.  
  3660.              For example, the following ACS:
  3661.  
  3662.                 <=Normal/123
  3663.  
  3664.              restricts access to those users who have a privilege level of
  3665.              50 or less and who also have keys 1, 2 and 3. Assuming the
  3666.              standard user classes, this could also be restated as:
  3667.  
  3668.                 <=30/123
  3669.  
  3670.  
  3671.  
  3672.              4. Customization                                           62
  3673.  
  3674.              In addition, an ACS can restrict an option to a user with a
  3675.              specific name or alias. The following ACS restricts a feature
  3676.              so that only the user named "John Doe" is able to access it:
  3677.  
  3678.                 name=John_Doe
  3679.  
  3680.              Notice that the space in the user's name is replaced with an
  3681.              underscore. An ACS may not include any spaces.
  3682.  
  3683.              Similarly, the following ACS restricts a command so that only
  3684.              the user with an alias of "Peter Rabbit" can access it:
  3685.  
  3686.                 alias=Peter_Rabbit
  3687.  
  3688.              Finally, boolean operators can also be included in an ACS
  3689.              definition. You can combine two existing ACSs by inserting
  3690.              the and operator ("&") between them:
  3691.  
  3692.                 10/123&<=Normal
  3693.  
  3694.              This ACS restricts a command to users who have a privilege
  3695.              level of at least 10 but less than 30 (the "Normal" privilege
  3696.              level). Users must also have keys 1, 2 and 3 to access this
  3697.              command.
  3698.  
  3699.              Similarly, the logical or operator can also be inserted be-
  3700.              tween two ACSs:
  3701.  
  3702.                 <=Normal/12|AsstSysop/!J
  3703.  
  3704.              This ACS restricts a command to users who either:
  3705.  
  3706.              *  have a privilege level of 30 ("Normal") or less and have
  3707.                 keys 1 and 2, or
  3708.  
  3709.              *  have a privilege level of at least 90 ("AsstSysOp") and do
  3710.                 not have key J.
  3711.  
  3712.              Most major Maximus subsystems use the ACS concept to restrict
  3713.              access to features. For example, every message and file area
  3714.              can be assigned an ACS to control which users get access to
  3715.              that area, and many settings in the system control file also
  3716.              accept an ACS. However, a small number of features can only
  3717.              be controlled on the basis of privilege level or user class.
  3718.  
  3719.  
  3720.              4.3. Display Files: *.mec and *.bbs
  3721.  
  3722.              All of the information files that Maximus displays to the
  3723.              user are stored in the .bbs and .mec file formats. Collec-
  3724.              tively, these are known as MECCA files or display files. Most
  3725.              of the system MECCA files are stored in the \max\misc and
  3726.  
  3727.  
  3728.  
  3729.              4. Customization                                           63
  3730.  
  3731.              \max\hlp directories, but you can add your own display files
  3732.              in other places.
  3733.  
  3734.              The names of many of the standard display files can be found
  3735.              in the system control file, but the names of some display
  3736.              files cannot be changed. Please see Appendix H for more in-
  3737.              formation on the names of these display files.
  3738.  
  3739.              You will notice that most of these files come in pairs: for
  3740.              every file with a .mec extension, there is always a file with
  3741.              a .bbs extension. Just like control files, MECCA files must
  3742.              be compiled before they can be used by Maximus.
  3743.  
  3744.              The .mec file is the source for a display file. You can edit
  3745.              the .mec file with a text editor to insert commands and dis-
  3746.              play text. After you have finished modifying the .mec file,
  3747.              the MECCA compiler must be run to convert it to a .bbs file.
  3748.  
  3749.              Compiling a file with MECCA is easy. Simply type in the com-
  3750.              mand "MECCA filename", where filename is the name of the .mec
  3751.              file to be compiled. For example, to compile the file ap-
  3752.              plic.mec into applic.bbs, enter the following at a command
  3753.              prompt:
  3754.  
  3755.                 cd \max\misc
  3756.                 mecca applic
  3757.  
  3758.              MECCA source files contain plain text to be displayed to the
  3759.              user, but they can also contain tokens to perform color
  3760.              changes, cursor control, conditionally display certain lines,
  3761.              and display system information. A MECCA token is a special
  3762.              keyword that is enclosed inside a pair of square brackets.
  3763.  
  3764.              For example, a .mec file that contains the following:
  3765.  
  3766.                 [white]Hello there, [user].
  3767.                 Are you having a nice [lightblue]day [white]today?
  3768.  
  3769.              will display "Hello there, John Doe" in white (assuming that
  3770.              the user's name is John Doe). It will then display "Are you
  3771.              having a nice" in white, the word "day" in blue, and the word
  3772.              "today?" in white.
  3773.  
  3774.              MECCA supports many other tokens that display information to
  3775.              the user or change screen attributes. MECCA allows you to em-
  3776.              bed user-specific or system-specific information into any
  3777.              display screen.
  3778.  
  3779.              To see an actual MECCA file, load the \max\misc\newuser2.mec
  3780.              file with an ASCII editor. As you can see, the file consists
  3781.              mainly of ASCII text, but a few special MECCA tokens have
  3782.              been inserted to colorize the screen and perform other ac-
  3783.              tions.
  3784.  
  3785.  
  3786.  
  3787.              4. Customization                                           64
  3788.  
  3789.              One of the main advantages of using MECCA is that only one
  3790.              set of display files needs to be created. Unlike other bulle-
  3791.              tin board packages where the SysOp must create both an ASCII
  3792.              and an ANSI version of a specific display file, Maximus auto-
  3793.              matically filters out color and graphics codes for those us-
  3794.              ers who do not support ANSI or AVATAR graphics.
  3795.  
  3796.              For compatibility reasons, Maximus comes with a utility to
  3797.              convert files containing ANSI graphics into MECCA files.
  3798.              Please see section 8.2 for more information.
  3799.  
  3800.              Although MECCA files are normally viewed by running Maximus
  3801.              and displaying the menu option or command that contains the
  3802.              display file, you can also use the ORACLE utility to display
  3803.              a MECCA file from the command prompt.
  3804.  
  3805.              For more information on creating MECCA files, please see sec-
  3806.              tion 17.
  3807.  
  3808.              For more information on using the MECCA compiler, please see
  3809.              section 8.8.
  3810.  
  3811.              For more information on ORACLE, please see section 8.10.
  3812.  
  3813.  
  3814.              4.4. Message Areas and File Areas
  3815.  
  3816.              The next step in customizing your system is to set up the
  3817.              message and file sections. The Maximus distribution kit comes
  3818.              preconfigured with a set of sample message and file areas,
  3819.              but most SysOps will want to customize these areas.
  3820.  
  3821.              All message areas are defined in the msgarea.ctl file. Like-
  3822.              wise, all file areas are defined in the filearea.ctl file.
  3823.  
  3824.              In Maximus, each area (whether a message area or a file area)
  3825.              must have a unique name. Area names can be up to 64 charac-
  3826.              ters long, and names can include both letters and numbers.
  3827.              Maximus supports a theoretically unlimited number of message
  3828.              and file areas, but it is better to start with a small number
  3829.              of areas and expand them as your system grows.
  3830.  
  3831.  
  3832.              4.4.1. Message Area Definitions
  3833.  
  3834.              A message area definition looks like this:
  3835.  
  3836.                 MsgArea name
  3837.                     % Other message area definition keywords
  3838.                     % go here.
  3839.                 End MsgArea
  3840.  
  3841.  
  3842.  
  3843.              4. Customization                                           65
  3844.  
  3845.              where name is the name of the message area to be defined. All
  3846.              of the keywords related to that area must be placed between
  3847.              the MsgArea keyword and the following End MsgArea keyword.
  3848.  
  3849.        Note! By default, all log-off comments are placed in message area
  3850.              1. If you wish to change the name for area 1, you must also
  3851.              change the Comment Area definition in the system control
  3852.              file.
  3853.  
  3854.              Some common message area definition keywords are described
  3855.              below. A complete list of keywords can be found in section
  3856.              18.6.
  3857.  
  3858.              ACS string
  3859.  
  3860.                 Restrict access to this area so that only those users who
  3861.                 satisfy the ACS string are allowed to see or enter the
  3862.                 area. This statement is required for all message areas.
  3863.  
  3864.              Desc text
  3865.  
  3866.                 Use text as the description for this area. Maximus will
  3867.                 display this description when the user requests a list of
  3868.                 areas.
  3869.  
  3870.              Path filename
  3871.  
  3872.                 filename specifies the physical disk file and/or directory
  3873.                 to use for storing messages.
  3874.  
  3875.                 For a Squish-format message area (default), filename must
  3876.                 contain the path and filename of the area (without an ex-
  3877.                 tension).
  3878.  
  3879.                 For a *.MSG-format message area, filename must contain only
  3880.                 the path of the area. (Only one *.MSG area can be stored in
  3881.                 any given directory.)
  3882.  
  3883.              Style flags
  3884.  
  3885.                 The flags option specifies a number of optional flags and
  3886.                 toggles for the message area. Multiple flags can be speci-
  3887.                 fied for a single message area by separating flag names
  3888.                 with spaces. Table 4.4 describes some of the more common
  3889.                 flags:
  3890.  
  3891.                 Table 4.4 Message Style Flags
  3892.  
  3893.                 Flag    Description
  3894.  
  3895.                 Pvt     Allow private messages in this area. Private mes-
  3896.                         sages can only be read by the SysOp, the sender,
  3897.  
  3898.  
  3899.  
  3900.              4. Customization                                           66
  3901.  
  3902.                         and the addressee.
  3903.  
  3904.                 Pub     Allow public messages in this area. Public mes-
  3905.                         sages can be read by anyone.
  3906.  
  3907.                 Squish  Store this area in the Squish format (default).
  3908.  
  3909.                 *.MSG   Store this area in the *.MSG format.
  3910.  
  3911.  
  3912.  
  3913.                 Most of these flags are optional. Please see section 18.6
  3914.                 for information on other supported styles.
  3915.  
  3916.              Tag name
  3917.  
  3918.                 This keyword tells Maximus to use name as the "tag" for
  3919.                 this area. If a tag is assigned to an area, Maximus will
  3920.                 write the tag out to the Log EchoMail filename after the
  3921.                 user logs off. This feature is normally used in conjunction
  3922.                 with EchoMail areas; the tag specified here should be the
  3923.                 same as the tag that you have defined for that area in your
  3924.                 EchoMail processor.
  3925.  
  3926.  
  3927.              4.4.2. File Area Definitions
  3928.  
  3929.              A file area definition looks like this:
  3930.  
  3931.                 FileArea name
  3932.                     % Other file area definition keywords
  3933.                     % go here.
  3934.                 End MsgArea
  3935.  
  3936.              where name is the name of the file area to be defined. All of
  3937.              the keywords related to that area must be placed between the
  3938.              FileArea keyword and the following End FileArea keyword.
  3939.  
  3940.              Some common file area definition keywords are described be-
  3941.              low. A complete list of keywords can be found in section
  3942.              18.7.
  3943.  
  3944.              ACS string
  3945.  
  3946.                 Restrict access to this area so that only those users who
  3947.                 satisfy the ACS string are allowed to see or enter the
  3948.                 area. This statement is required for all message areas.
  3949.  
  3950.              Desc text
  3951.  
  3952.                 Use text as the description for this area. Maximus will
  3953.                 display this description when the user requests a list of
  3954.                 areas.
  3955.  
  3956.  
  3957.  
  3958.              4. Customization                                           67
  3959.  
  3960.              Download path
  3961.  
  3962.                 This keyword tells Maximus where to find the files con-
  3963.                 tained within this file area. The files that the users are
  3964.                 to download must be contained within this directory.
  3965.  
  3966.              Upload path
  3967.  
  3968.                 This keyword tells Maximus where to place uploaded files.
  3969.                 There are two options for defining an upload path:
  3970.  
  3971.                 * Set the upload path to point to the same directory as
  3972.                   the download path. With this configuration, files will
  3973.                   be made available to other users as soon as they are up-
  3974.                   loaded. (However, users must ensure that they change to
  3975.                   the correct file area before uploading files.)
  3976.  
  3977.                 * Set the upload path in all file areas to point to one
  3978.                   common directory. This directory can then be configured
  3979.                   as the download path for an area that can be accessed
  3980.                   only by the SysOp.
  3981.  
  3982.                   This option is the most secure, since it allows the Sy-
  3983.                   sOp to check uploaded files before they are put on-line
  3984.                   for other users. Users will only be able to see the file
  3985.                   after the SysOp has checked the file and used the Hurl
  3986.                   command to move it to another file area.
  3987.  
  3988.  
  3989.              4.4.3. Custom Message and File Area Menus
  3990.  
  3991.              By default, Maximus will dynamically generate a menu when us-
  3992.              ers select the Area Change command from the message or file
  3993.              area menus. This display can be controlled to an extent, us-
  3994.              ing the Format MsgFormat and Format FileFormat definitions,
  3995.              but these commands may still be too restrictive for some Sy-
  3996.              sOps.
  3997.  
  3998.              Consequently, Maximus allows you to completely disable the
  3999.              automatic menu generation feature and replace it with custom
  4000.              .mec screens. The Uses MsgAreas and Uses FileAreas statements
  4001.              (in the system control file) instruct Maximus to display the
  4002.              specified file instead of generating an area menu of its own.
  4003.  
  4004.              While these files give you a large degree of flexibility, us-
  4005.              ing a custom display file means that you must remember to
  4006.              modify the display file when you add or remove an area.
  4007.  
  4008.  
  4009.              4.4.4. Message Area and File Area Hierarchies
  4010.  
  4011.              Maximus allows you to group your message and file areas into
  4012.              logical, multi-level hierarchies. By default, all message and
  4013.  
  4014.  
  4015.  
  4016.              4. Customization                                           68
  4017.  
  4018.              file areas are stored in a "flat" name space, but you can add
  4019.              divisions to your message area and file area control files to
  4020.              group areas in a logical manner.
  4021.  
  4022.              For example, if your system supported the following message
  4023.              areas:
  4024.  
  4025.                 Lexus
  4026.                 Lawnmowers
  4027.                 C
  4028.                 BMW
  4029.                 Pascal
  4030.                 Shovels
  4031.                 Jaguar
  4032.  
  4033.              the areas could be grouped in a more logical structure as
  4034.              follows:
  4035.  
  4036.                 cars.lexus
  4037.                 cars.bmw
  4038.                 cars.jaguar
  4039.                 programming.c
  4040.                 programming.pascal
  4041.                 garden.lawnmowers
  4042.                 garden.shovels
  4043.  
  4044.              By adding the appropriate MsgAreaDivision records to your
  4045.              message area control file, Maximus can automatically insert
  4046.              the "cars." or "programming." prefix for each area. Maximus
  4047.              will also present the list of areas to the user in a logical
  4048.              manner. For example, the top level message area menu might
  4049.              look something like this:
  4050.  
  4051.                 Message Areas --------------------
  4052.  
  4053.                 cars         ... DIVISION: Cars
  4054.                 programming  ... DIVISION: Langs
  4055.                 garden       ... DIVISION: Gardening
  4056.  
  4057.              If a user selected "cars" at the prompt, Maximus would dis-
  4058.              play a submenu of all of the areas in that division, includ-
  4059.              ing cars.lexus, cars.bmw and cars.jaguar.
  4060.  
  4061.              Maximus also supports nested message area divisions. For ex-
  4062.              ample, the "cars" division could be subdivided into two sepa-
  4063.              rate groups of areas, such as "cars.luxury" and
  4064.              "cars.economy."
  4065.  
  4066.              All of the comments related to message areas also apply
  4067.              equally to file areas. The description below refers to mes-
  4068.              sage area divisions only, but you can apply the same concept
  4069.              to file areas by replacing MsgDivisionBegin with FileDivi-
  4070.  
  4071.  
  4072.  
  4073.              4. Customization                                           69
  4074.  
  4075.              sionBegin, MsgDivisionEnd with FileDivisionEnd, and MsgArea
  4076.              with FileArea.
  4077.  
  4078.              To create a message area division, you must place the follow-
  4079.              ing statement before the definition of the first message area
  4080.              to be included in the division:
  4081.  
  4082.                 MsgDivisionBegin name acs display_file description
  4083.  
  4084.              In addition, you must place the following statement after the
  4085.              end of the last message area to be included:
  4086.  
  4087.                 MsgDivisionEnd
  4088.  
  4089.              The name parameter is the name of the message area division.
  4090.              From the example above, one might use a name of "cars" or
  4091.              "garden." Maximus will automatically add this name, followed
  4092.              by a period ("."), to the names of any message areas defined
  4093.              within this division.
  4094.  
  4095.              The acs parameter is the ACS that controls access to the mes-
  4096.              sage area division. A user can only see this area division if
  4097.              the user's privilege level passes the access control check.
  4098.  
  4099.        Warni The acs parameter only controls the access level required for
  4100.          ng! users to see the division on the message area menu. Even if
  4101.              users cannot see a message area division, if they know the
  4102.              name of an area inside the division, and if they have a
  4103.              privilege level high enough to access the message area (but
  4104.              not the division), the users can change directly to that area
  4105.              anyway. For this reason, the ACS of a message area definition
  4106.              should be at least as restrictive as the ACS of the MsgDivi-
  4107.              sionBegin statement.
  4108.  
  4109.              The display_file parameter instructs Maximus to display the
  4110.              specified file when the user requests a list of areas in the
  4111.              division, rather than automatically generating a menu of its
  4112.              own. This display file is normally used in conjunction with
  4113.              the Uses MsgAreas definition in the system control file. If
  4114.              you do not wish to use a custom display file, specify a "."
  4115.              to instruct Maximus to generate the area list automatically.
  4116.  
  4117.              The description parameter is a short description of the con-
  4118.              tents of the division. Maximus will display this description
  4119.              on the message area menu when the user requests a list of ar-
  4120.              eas.
  4121.  
  4122.              For example, to implement the message division structure de-
  4123.              scribed in the previous example, use the following syntax:
  4124.  
  4125.                 MsgDivisionBegin cars   Demoted . DIVISION: Cars
  4126.                   MsgArea lexus
  4127.                        % Definitions for the Lexus area go here
  4128.  
  4129.  
  4130.  
  4131.              4. Customization                                           70
  4132.  
  4133.                   End MsgArea
  4134.  
  4135.                   MsgArea bmw
  4136.                        % Definitions for the BMW area go here
  4137.                   End MsgArea
  4138.  
  4139.                   MsgArea jaguar
  4140.                        % Definitions for the Jaguar area go here
  4141.                   End MsgArea
  4142.                 MsgDivisionEnd
  4143.  
  4144.                 MsgDivisionBegin programming Demoted . DIVISION: Langs
  4145.                   MsgArea c
  4146.                        % Definitions for the C area go here
  4147.                   End MsgArea
  4148.  
  4149.                   MsgArea pascal
  4150.                        % Definitions for the Pascal area go here
  4151.                   End MsgArea
  4152.                 MsgDivisionEnd
  4153.  
  4154.                 MsgDivisionBegin garden Demoted . Gardening
  4155.                   MsgArea lawnmowers
  4156.                        % Definitions for the lawnmowers area go here
  4157.                   End MsgArea
  4158.  
  4159.                   MsgArea shovels
  4160.                        % Definitions for the shovels area go here
  4161.                   End MsgArea
  4162.                 MsgDivisionEnd
  4163.  
  4164.  
  4165.              4.5. Maintaining File Areas
  4166.  
  4167.              Message areas can be created quite easily, but file areas re-
  4168.              quire a fair amount of maintenance to run properly. Not only
  4169.              do you need to create file area definitions, but you must
  4170.              also create listings of files which can be downloaded by the
  4171.              user. (However, if you wish to create a blank file area, no
  4172.              extra work is required, since Maximus will create a file
  4173.              listing as soon as a user uploads a file to that area.)
  4174.  
  4175.  
  4176.              4.5.1. Creating File Listings
  4177.  
  4178.              To place files in a newly-created file area, you must create
  4179.              an ASCII listing of the files in the area. If you already
  4180.              have a directory containing the files to be added, you should
  4181.              first copy those files to the directory specified in the file
  4182.              area's Download statement.
  4183.  
  4184.              Next, from the command prompt, change the current directory
  4185.              to the directory specified in the area's Download path. Next,
  4186.  
  4187.  
  4188.  
  4189.              4. Customization                                           71
  4190.  
  4191.              enter the following command to create the initial file cata-
  4192.              log:
  4193.  
  4194.                 for %f in (*.*) do echo %f >>files.bbs
  4195.  
  4196.              If you wish to run this command from a batch file, instead of
  4197.              from the command prompt, enter this instead:
  4198.  
  4199.                 for %%f in (*.*) do echo %%f >>files.bbs
  4200.  
  4201.              After a bit of disk activity, the file listing should be cre-
  4202.              ated for you. Although this will create a listing of file
  4203.              names, most users will also want to see file descriptions. To
  4204.              add file descriptions, run an ASCII editor (such as the DOS
  4205.              edit.com or the OS/2 e.exe) and load the files.bbs file.
  4206.  
  4207.              Inside files.bbs, you should see a list of the files in the
  4208.              directory. If you wish to add a description for a particular
  4209.              file, simply add one or more spaces after the filename and
  4210.              insert your description there. A description can be up to
  4211.              1024 characters long; although only 48 characters can be dis-
  4212.              played on one line of the file catalog, Maximus will auto-
  4213.              matically wordwrap the rest of the text onto the following
  4214.              lines.
  4215.  
  4216.              The files.bbs in a hypothetical file area could look like
  4217.              this:
  4218.  
  4219.                 DEMO.LST      Description of product demonstration
  4220.                 INFO.TXT      Information about this system
  4221.                 RESULTS.ZIP   Results from the last quarter
  4222.  
  4223.              To add files to the file listing after performing the initial
  4224.              "for %f" command, you can simply use a text editor to insert
  4225.              a line in files.bbs and add the name and description for the
  4226.              file.
  4227.  
  4228.              Similarly, to delete a file from the listing, just remove the
  4229.              line containing the file entry from files.bbs. You should
  4230.              also delete the actual file from the download directory.
  4231.  
  4232.              When using the default File Date Automatic setting in the
  4233.              system control file, Maximus will automatically colorize the
  4234.              listing and place the file's size and date beside the file-
  4235.              name.
  4236.  
  4237.              In addition, Maximus allows files to be marked as "free down-
  4238.              loads". Files can be marked for "free download bytes" (the
  4239.              file does not count against the user's download limit) or
  4240.              "free download time" (the file does not count against the
  4241.              user's time limit), or both.
  4242.  
  4243.  
  4244.  
  4245.              4. Customization                                           72
  4246.  
  4247.              To mark a file as a free download, you must add a slash se-
  4248.              quence before a file's description. For a free time download,
  4249.              insert "/t" before the description. For a free bytes down-
  4250.              load, insert "/b" before the description. For both free time
  4251.              and free bytes, use "/tb".
  4252.  
  4253.              For example, to ensure that the Maximus 3.0 distribution
  4254.              files do not count against the user's download quota, use the
  4255.              following:
  4256.  
  4257.                   MAX300C.ZIP /b This is Maximus 3.0.
  4258.  
  4259.              If you want to count the download against the user's byte to-
  4260.              tal (but not the user's time limit), use the following:
  4261.  
  4262.                   MAX300C.ZIP /t This is Maximus 3.0.
  4263.  
  4264.              Similarly, if you want both free time and bytes to be given
  4265.              to the user, use the following:
  4266.  
  4267.                   MAX300P.ZIP /tb This is Maximus 3.0.
  4268.  
  4269.              Finally, you can add comments to files.bbs which are not spe-
  4270.              cifically related to a file. If the first character on a line
  4271.              is a dash ("-") or a space (" "), Maximus will treat the line
  4272.              as a comment and display it to the user. In addition, if the
  4273.              first character on the line is a dash, the line will be dis-
  4274.              played in white. If the first character is a space, Maximus
  4275.              will display the line in the current color (which is normally
  4276.              cyan).
  4277.  
  4278.  
  4279.              4.5.2. Global Downloading, Fast Locates and Duplicate Files
  4280.  
  4281.              The global downloading feature allows users to select a file
  4282.              for download from any point in the system, regardless of the
  4283.              file area where the file is stored. For example, if your sys-
  4284.              tem had a file in area "os2" called fix.zip, a user could en-
  4285.              ter "d fix.zip" from file area "dos" and still download the
  4286.              correct file.
  4287.  
  4288.              The fast locate feature allows Maximus to perform very fast
  4289.              file area searches using the Locate command.
  4290.  
  4291.              The duplicate checking (or dupe check) feature allows Maximus
  4292.              to compare the filenames of uploaded files with the files
  4293.              that are available for download. Maximus can be configured to
  4294.              automatically reject files that already exist elsewhere in
  4295.              the file areas.
  4296.  
  4297.              To enable any of these features, you must use the FB utility
  4298.              to create a compiled file database. FB scans the files.bbs
  4299.              catalogs in all file areas and creates a binary file data-
  4300.  
  4301.  
  4302.  
  4303.              4. Customization                                           73
  4304.  
  4305.              base. This database is required for all of the features men-
  4306.              tioned above.
  4307.  
  4308.              Every time you change your file areas, you should run the
  4309.              following command:
  4310.  
  4311.                 fb -a
  4312.  
  4313.              This command tells FB to compile a database containing all of
  4314.              the file areas defined in filearea.ctl. (On large systems,
  4315.              this command may take a long time to execute. For information
  4316.              on incremental FB compiles, please see section 8.5.)
  4317.  
  4318.              After running FB, the global downloading and fast locate fea-
  4319.              tures are automatically enabled. However, you may need to en-
  4320.              able the Upload Check Dupe feature in the system control file
  4321.              to use duplicate file checking.
  4322.  
  4323.  
  4324.              4.5.3. CD-ROM Handling
  4325.  
  4326.              To set up your system to retrieve files from a CD-ROM, you
  4327.              must first create a FileArea definition for each directory on
  4328.              the CD. However, to inform Maximus that the area is stored on
  4329.              slow media, you must add the following keyword to the file
  4330.              area definition:
  4331.  
  4332.                 Type CD
  4333.  
  4334.              This line tells Maximus to do two things:
  4335.  
  4336.              *  Maximus will only access the actual drive when absolutely
  4337.                 necessary. For example, this means that Maximus will not
  4338.                 try to validate the directory when displaying an area list.
  4339.  
  4340.              *  Files to be downloaded from this area will be copied to a
  4341.                 staging area on your hard drive before the transfer. This
  4342.                 helps prevent thrashing when multiple users are downloading
  4343.                 from a rotary CD changer. (The destination directory for
  4344.                 this copy operation can be set with the Stage Path defini-
  4345.                 tion in the system control file.)
  4346.  
  4347.              *  SILT will not check to see whether or not the directory ex-
  4348.                 ists. This means that you can compile your system with sup-
  4349.                 port for many different CDs, even if your system only has
  4350.                 one CD-ROM drive.
  4351.  
  4352.          DOS In addition, when setting up your system with a CD, do not
  4353.        only! forget to edit the Save Directories keyword in the system
  4354.              control file. This keyword tells the DOS version of Maximus
  4355.              to save the current directory for every drive in a list of
  4356.              drives. However, since CD-ROM drives have removable media,
  4357.  
  4358.  
  4359.  
  4360.              4. Customization                                           74
  4361.  
  4362.              you must remove the drive letter corresponding to the CD-ROM
  4363.              from the Save Directories statement.
  4364.  
  4365.  
  4366.              4.5.3.1. File Listings
  4367.  
  4368.              Some CD-ROMs may already be set up for use with a Maximus
  4369.              system. Such CD-ROMs will come with a files.bbs file in every
  4370.              directory that contains files to be downloaded. If this is
  4371.              the case, you do not need to do anything further.
  4372.  
  4373.              However, a number of other CD-ROMs are not set up for BBS use
  4374.              (or do not have a standard Maximus files.bbs listing). If
  4375.              this is the case, you need to construct your own listing of
  4376.              files in each directory.
  4377.  
  4378.              To construct your own file listing for one area, add the fol-
  4379.              lowing line to the file area definition:
  4380.  
  4381.                 FileList   c:\path\filename.bbs
  4382.  
  4383.              The FileList keyword instructs Maximus to look for a
  4384.              files.bbs-like catalog with the specified name. The CD-ROM is
  4385.              read-only, so you need to point filename to a file on your
  4386.              hard drive.
  4387.  
  4388.              In this file, you must place a files.bbs-like listing of
  4389.              files in the area. The file name should come first, followed
  4390.              by the file description, just as in files.bbs.
  4391.  
  4392.              When a user accesses the area, instead of looking in the
  4393.              Download path for the files.bbs file, Maximus will look for
  4394.              the file list specified in the FileList statement.
  4395.  
  4396.              For example, a sample CD-ROM area definition might look like
  4397.              this:
  4398.  
  4399.                 FileArea apl
  4400.                   Type       CD
  4401.                   Desc       The APL Programming Language
  4402.                   Download   g:\msdos\apl
  4403.                   Upload     c:\max\file\upload
  4404.                   FileList   c:\max\lists\apl.bbs
  4405.                 End FileArea
  4406.  
  4407.              In this case, the c:\max\lists\apl.bbs file would be a file
  4408.              catalog listing all of the files in the g:\msdos\apl direc-
  4409.              tory.
  4410.  
  4411.  
  4412.  
  4413.              4. Customization                                           75
  4414.  
  4415.              4.5.3.2. Listing Date and Size Formats
  4416.  
  4417.              Maximus supports three different styles of "file dating."
  4418.              These formats are:
  4419.  
  4420.              Automatic dating. Maximus retrieves a file's date and size
  4421.              from the directory entry. This is the default style. When FB
  4422.              builds the file database, and when a user does a file listing
  4423.              for a single area, Maximus retrieves file information from
  4424.              the download path.
  4425.  
  4426.              List dating. Maximus assumes that a file's date and size are
  4427.              stored as part of the file description in the files.bbs list-
  4428.              ing (or the FileList catalog for the area). FB will read the
  4429.              file description and parse dates and sizes in the form "mm-
  4430.              dd-yy size" or "size mm-dd-yy." FB will incorporate this in-
  4431.              formation into the compiled file database. Maximus will also
  4432.              colorize the file information when displaying a directory
  4433.              listing. When list dating is used, the download directory is
  4434.              not examined at all.
  4435.  
  4436.              Manual dating. Maximus does not attempt to process or display
  4437.              file dates or sizes in any manner whatsoever. The
  4438.              File_NewFiles option and the "L*" (or "F*") commands cannot
  4439.              be used to search based on file dates when this dating method
  4440.              is selected.
  4441.  
  4442.              The Type keywords shown below in Table 4.5 can be used to
  4443.              specify one of these dating styles.
  4444.  
  4445.              Table 4.5 File Area Date Styles
  4446.  
  4447.               Keyword           Style
  4448.  
  4449.               Type DateAuto     Automatic file dates.
  4450.               Type DateList     List dating.
  4451.               Type DateManual   Manual file dates.
  4452.  
  4453.  
  4454.              The DateAuto style is well suited for file areas stored on
  4455.              your hard drive. Aside from file areas that never change,
  4456.              this is usually the best option to use.
  4457.  
  4458.              However, the DateList style is much more appropriate for CD-
  4459.              ROMs. If the CD comes with a file catalog that contains file
  4460.              sizes and dates, select the DateList style and use the
  4461.              FileList keyword to specify the name of the file containing
  4462.              the file list.
  4463.  
  4464.              For example, if the CD-ROM vendor has placed a DateList-
  4465.              compatible file list in the download directory (called
  4466.              00index.txt), the following file area definition can be used:
  4467.  
  4468.  
  4469.  
  4470.              4. Customization                                           76
  4471.  
  4472.                 FileArea apl
  4473.                   Type       CD DateList
  4474.                   Desc       The APL Programming Language
  4475.                   Download   g:\msdos\apl
  4476.                   Upload     c:\max\file\upload
  4477.                   FileList   g:\msdos\apl\00index.txt
  4478.                 End FileArea
  4479.  
  4480.              If you use a DateList file area, Maximus will not examine the
  4481.              drive at all when the user requests a file listing. In addi-
  4482.              tion, the CD-ROM does not need to be in the drive when FB is
  4483.              asked to build the file database. For CD-ROMs, the DateList
  4484.              option is the quickest in terms of overall system perform-
  4485.              ance, and it is much easier to maintain than the other two
  4486.              options.
  4487.  
  4488.  
  4489.              4.5.3.3. CD-ROM areas and DateAuto Processing
  4490.  
  4491.              If you still choose to use DateAuto processing with a CD-ROM
  4492.              file area, you must follow the following procedure to main-
  4493.              tain the file catalog.
  4494.  
  4495.              Normally, since DateAuto processing reads information from
  4496.              the file download directories, all of your file areas must be
  4497.              accessible when you run FB. However, if you have only one CD-
  4498.              ROM drive and many CDs, you may wish to create file areas for
  4499.              all of your CDs, even though only one CD can be on-line at a
  4500.              time.
  4501.  
  4502.              Using the DateList option is preferable when you want to do
  4503.              this. However, if you would like to use DateAuto processing,
  4504.              you must follow this procedure when building your file cata-
  4505.              log with FB:
  4506.  
  4507.              1. Remove all CDs from the computer and run "fb -a". This com-
  4508.                 piles the file database information for file areas on your
  4509.                 hard drive.
  4510.  
  4511.              2. Insert the first CD into the drive. Run FB only over those
  4512.                 areas which are contained on that CD. (If you have subdi-
  4513.                 vided your file areas using FileDivision statements, you
  4514.                 can tell FB to compile only a certain file area tree using
  4515.                 wildcards, such as with "fb simtel.*". Otherwise, you will
  4516.                 have to specify each area separately on the command line
  4517.                 like this: "fb area1 area2 area3".)
  4518.  
  4519.              3. Remove the first CD and repeat step 2 for all remaining
  4520.                 CDs.
  4521.  
  4522.              4. After completing step 2 for all of your CDs, the file area
  4523.                 database will be completely built. However, to prevent FB
  4524.                 from trying to recompile CD areas when the CD-ROM is not in
  4525.  
  4526.  
  4527.  
  4528.              4. Customization                                           77
  4529.  
  4530.                 the drive, you must always run FB with the "fb -s" parame-
  4531.                 ter (which causes it to skip the CD areas). After the file
  4532.                 database is built, if you omit the -s parameter even once,
  4533.                 the compiled file information for your CD-ROMs may be over-
  4534.                 written.
  4535.  
  4536.  
  4537.              4.6. Barricades and Extended Barricade Files
  4538.  
  4539.              The Barricade keyword in the message and file areas tells
  4540.              Maximus that you wish to protect the area with a password, or
  4541.              that you want to grant different access levels to certain us-
  4542.              ers while they are in that area.
  4543.  
  4544.              When a user enters a barricaded area, the Uses Barricade file
  4545.              is shown, and the user is given three tries to enter the cor-
  4546.              rect access code.
  4547.  
  4548.              The access codes required to enter a barricaded area are con-
  4549.              tained in a barricade file. The Barricade keyword in the area
  4550.              definition must point to a barricade file.
  4551.  
  4552.  
  4553.              4.6.1. Barricade Files
  4554.  
  4555.              A barricade file is a straight ASCII text file containing a
  4556.              list of passwords, with each password followed by the privi-
  4557.              lege level to grant to users who enter the correct password.
  4558.  
  4559.              Each line of the barricade file is in the following format:
  4560.  
  4561.                 <password> <priv>
  4562.  
  4563.              <password> is the password which grants a privilege level of
  4564.              <priv> to the user. <priv> can only specify a numeric privi-
  4565.              lege level or a class name. (Keys are not valid in the <priv>
  4566.              string.)
  4567.  
  4568.              For example:
  4569.  
  4570.                 helloworld SysOp
  4571.                 kentucky   Clerk
  4572.                 cleanse    Normal
  4573.                 scum       Demoted
  4574.  
  4575.              If a user enters an area with this barricade file and types
  4576.              "helloworld" at the password prompt, the user will be granted
  4577.              access to the area, and the user's privilege level will be
  4578.              set to SysOp while in the area.
  4579.  
  4580.              Similarly, if the user typed "kentucky," the user's privilege
  4581.              level would be temporarily altered to Clerk while inside that
  4582.              area.
  4583.  
  4584.  
  4585.  
  4586.              4. Customization                                           78
  4587.  
  4588.              In addition, if you specify "NoAccess" in the <priv> field, a
  4589.              user who enters the specified password will be denied access
  4590.              and told that the area does not exist.
  4591.  
  4592.  
  4593.              4.6.2. Extended Barricade Files
  4594.  
  4595.              Maximus supports the "extended" barricade file concept. An
  4596.              extended barricade file allows users to be promoted without
  4597.              using passwords.
  4598.  
  4599.              Before displaying the Uses Barricade file, Maximus will
  4600.              quickly scan the barricade file to see if it uses the ex-
  4601.              tended barricade syntax. If so, Maximus skips the Uses Barri-
  4602.              cade display and processes the barricade file directly.
  4603.  
  4604.              Each line in an extended barricade file has the following
  4605.              format:
  4606.  
  4607.                 !<user_name>  <priv>
  4608.                   or
  4609.                 !All          [priv]
  4610.  
  4611.              The "!" in the first column of each line is not optional. The
  4612.              "!" distinguishes an extended barricade file from a normal
  4613.              barricade file.
  4614.  
  4615.              <user_name> is the name of the user whose access level is to
  4616.              be promoted. No spaces can be present in <user_name>, so re-
  4617.              place spaces with underscores. (For example, to use Joe SysOp
  4618.              in an extended barricade, you would have to use "Joe_SysOp"
  4619.              for the <user_name>.)
  4620.  
  4621.              If Maximus matches the name for the user trying to enter the
  4622.              barricaded area, the user's privilege level is altered to
  4623.              <priv> with no questions asked.
  4624.  
  4625.              In addition, if the user's name is not explicitly found in
  4626.              the barricade file, Maximus will "fall through" to the op-
  4627.              tional "!All" keyword.
  4628.  
  4629.              If you use "!All" by itself, without specifying a privilege
  4630.              level, Maximus will let other users into the area using their
  4631.              real privilege levels. If you do specify a privilege level
  4632.              after the "!All" keyword, Maximus will let all users enter
  4633.              the area and promote all of them to a level of [priv].
  4634.  
  4635.              The "!All" statement must be at the very end of the barricade
  4636.              file to function properly.
  4637.  
  4638.              Finally, you can even use the "NoAccess" privilege level with
  4639.              extended barricades. This allows you to create a barricaded
  4640.              area that is completely invisible to certain users.
  4641.  
  4642.  
  4643.  
  4644.              4. Customization                                           79
  4645.  
  4646.              For example:
  4647.  
  4648.                 !Jesse_Hollington    Clerk
  4649.                 !Steven_Bonisteel    Clerk
  4650.                 !Hubert_Lai          Privil
  4651.                 !All                 Demoted
  4652.  
  4653.              This file assigns the privilege level of "Clerk" to the first
  4654.              two users, assigns the "Privil" level to the third user, and
  4655.              gives all other users a privilege level of "Demoted". (To
  4656.              prevent anyone except the above three users from accessing
  4657.              the area, the "Demoted" could be replaced with a "NoAccess".)
  4658.  
  4659.  
  4660.              4.7. Menus
  4661.  
  4662.              This section describes how to configure different parts of
  4663.              the Maximus menu system.
  4664.  
  4665.  
  4666.              4.7.1. Customizing Menu Options
  4667.  
  4668.              The system menus are completely redefinable and offer a great
  4669.              deal of flexibility. However, if you are just starting a new
  4670.              Maximus system, it is best to skip making major menu changes
  4671.              until your system is up and running.
  4672.  
  4673.              However, even novices can change the access levels required
  4674.              to access particular commands in the menus control file. The
  4675.              access control string (ACS) for each menu option is normally
  4676.              located in the second or third column of each menu option.
  4677.              You can easily change these ACS definitions to suit your own
  4678.              system's privilege level or user class scheme.
  4679.  
  4680.              You can also modify the "Command as it appears to the user"
  4681.              field with a certain degree of safety. This command is what
  4682.              is shown on the screen when Novice-level menus are active.
  4683.  
  4684.              However, when changing menu commands, ensure that the first
  4685.              character in the command is unique among all options on that
  4686.              menu. When the user enters a letter at a menu, Maximus will
  4687.              process all commands that begin with that letter. Hence, if
  4688.              you use a letter that has already been used by another com-
  4689.              mand, confusing things will happen when a user gets to that
  4690.              menu.
  4691.  
  4692.  
  4693.              4.7.2. Custom Menu Display Files
  4694.  
  4695.              Maximus allows you to create custom menus with relative ease.
  4696.              Instead of displaying the standard yellow and gray menu,
  4697.              Maximus can be configured to display a user-defined .mec or
  4698.              .bbs file.
  4699.  
  4700.  
  4701.  
  4702.              4. Customization                                           80
  4703.  
  4704.              To add a custom menu file, simply insert a MenuFile keyword
  4705.              at the top of the appropriate menu definition in menus.ctl.
  4706.  
  4707.              Some of the following tips may be helpful when creating cus-
  4708.              tom menus:
  4709.  
  4710.              *  When using a custom menu that contains the [cls] token, the
  4711.                 output from some of the internal commands (such as the Ver-
  4712.                 sion command) may disappear, since the [cls] token in the
  4713.                 menu erases it before it can be seen.
  4714.  
  4715.                 To solve this problem, you must link a Press_Enter menu op-
  4716.                 tion after the appropriate command. This will cause Maximus
  4717.                 to wait until the user presses <enter> before redisplaying
  4718.                 the menu. For more details, please see section 4.7.3.
  4719.  
  4720.                 For example, to make Maximus wait after displaying the ver-
  4721.                 sion screen, you can use something like this:
  4722.  
  4723.                       Version                Demoted "Version"
  4724.                 NoDsp Press_Enter            Demoted "V"
  4725.  
  4726.                 This method is described in more detail in the following
  4727.                 section.
  4728.  
  4729.              *  When designing a custom menu with an input prompt at the
  4730.                 bottom, you may have some trouble getting the cursor to
  4731.                 stop in the appropriate place. Most text editors automati-
  4732.                 cally insert an <enter> after the last line of the file;
  4733.                 since Maximus reads the entire file, this causes the cursor
  4734.                 to skip down to the next line when the entire file is dis-
  4735.                 played.
  4736.  
  4737.                 Three possible solutions to this problem are:
  4738.  
  4739.                 1.Use a text editor that does not insert carriage returns
  4740.                   at the end of files.
  4741.  
  4742.                 2.If you are using a .mec file to create the menu, insert
  4743.                   a [quit] token where you want the cursor to stop. As
  4744.                   soon as Maximus encounters this token, it will stop dis-
  4745.                   playing the file without displaying the extra carriage
  4746.                   return.
  4747.  
  4748.                 3.If you are creating the menu file manually, you can in-
  4749.                   sert the compiled equivalent of the [quit] token di-
  4750.                   rectly into the .bbs file. The compiled equivalent is
  4751.                   "<ctrl-o>Q".
  4752.  
  4753.  
  4754.  
  4755.              4. Customization                                           81
  4756.  
  4757.              4.7.3. Linking Menu Options
  4758.  
  4759.              When working with custom menus, the output of some of inter-
  4760.              nal Maximus menu options may occasionally not fit in with the
  4761.              layout of your menu. For example, if you are using a custom
  4762.              menu that always clears the screen, the output of some com-
  4763.              mands may disappear before the user has a chance to read it.
  4764.  
  4765.              The solution to this problem is menu option linking.
  4766.  
  4767.              When the user selects a key, Maximus will search the entire
  4768.              menu for a menu option that has a description starting with
  4769.              that key. When it finds one, it executes the specified op-
  4770.              tion.
  4771.  
  4772.              However, Maximus continues to search for other commands with
  4773.              that key, even after executing the first menu command. This
  4774.              means that a number of menu commands can be tied to a single
  4775.              keystroke. (To prevent the second and subsequent menu options
  4776.              from appearing on the menu, use the NoDsp modifier in front
  4777.              of the menu option.)
  4778.  
  4779.              Consider this scenario: a user selects a message area and be-
  4780.              gins to read messages. The standard message menu is quite
  4781.              large and it leaves little space on-screen for messages. How-
  4782.              ever, if you include something like this on the message menu:
  4783.  
  4784.                        Read_Next               Demoted "Next Msg"
  4785.                 NoDsp  Display_Menu    READMSG Demoted "N"
  4786.                        Read_Previous           Demoted "Previous Msg"
  4787.                 NoDsp  Display_Menu    READMSG Demoted "P"
  4788.  
  4789.              after the user selects a message with Next or Prior, Maximus
  4790.              will automatically display the READMSG menu. This menu can
  4791.              then display only a limited subset of commands that are use-
  4792.              ful when reading messages.
  4793.  
  4794.  
  4795.              4.8. QWK Mail Packing
  4796.  
  4797.              Maximus includes a built-in QWK mail facility for off-line
  4798.              mail reading. This feature allows callers to log on, pack up
  4799.              messages from one or more message areas, and download a com-
  4800.              pressed mail bundle for off-line reading and reply. The
  4801.              packer is fully integrated with the rest of the BBS, and the
  4802.              packer will automatically adjust itself as message areas are
  4803.              added to or deleted from your system.
  4804.  
  4805.              All of the QWK-specific information is stored in the reader
  4806.              control file. To customize the off-line reader, you should
  4807.              edit a copy of reader.ctl with a text editor and make the
  4808.              following modifications.
  4809.  
  4810.  
  4811.  
  4812.              4. Customization                                           82
  4813.  
  4814.              *  You must give a unique name (of up to 8 characters) for the
  4815.                 Packet Name keyword. This keyword is used when creating QWK
  4816.                 packets to send to your users. (Do not include the .qwk ex-
  4817.                 tension.) Try to make this name describe your BBS in some
  4818.                 way, such as an abbreviation truncated to eight characters.
  4819.  
  4820.              *  You should also modify the Phone Number keyword to reflect
  4821.                 your system's true phone number. Maximus does not use this
  4822.                 information, but users who download QWK packets will re-
  4823.                 ceive this phone number along with their mail.
  4824.  
  4825.              *  You may also want to customize the Max Messages keyword. If
  4826.                 you run a busy system and wish to restrict callers from
  4827.                 downloading more than 200 messages at a time, you can set a
  4828.                 maximum value here. In the distribution control file, users
  4829.                 are prevented from downloading more than 1200 messages at a
  4830.                 time. To completely disable this limit, comment out the Max
  4831.                 Messages keyword.
  4832.  
  4833.              Beyond this initial configuration, the QWK packer is com-
  4834.              pletely self-maintaining. No extra maintenance is required.
  4835.              However, if you would like to add extra features to the off-
  4836.              line mail packets, such as bulletin listings and new file
  4837.              lists, please see section 5.3.
  4838.  
  4839.  
  4840.              4.9. Multilingual Support
  4841.  
  4842.              Maximus 3.0 is fully multilingual. Up to eight different lan-
  4843.              guage files can be defined in the system language control
  4844.              file, and users can switch between languages at any time
  4845.              (using the Chg_Language option on the Change Setup menu).
  4846.  
  4847.              The language files contain all of the text strings that Maxi-
  4848.              mus sends to the user, including prompts, system messages and
  4849.              command keys. A separate language file can be created to use
  4850.              "Oui" and "Non" instead of "Yes" and "No"; even the key-
  4851.              strokes for various internal options can be changed.
  4852.  
  4853.              Language files are divided into two distinct sections. Each
  4854.              language file has a set of strings to be displayed to the
  4855.              user, and each also has a second set of strings to be dis-
  4856.              played to the SysOp. By default, the SysOp always sees the
  4857.              text strings contained in the first language file defined in
  4858.              language.ctl, regardless of the language selected by the
  4859.              user.
  4860.  
  4861.              This means that the user can go through a set of menus in
  4862.              German, but the SysOp will still be able to read the pop-up
  4863.              menus and the system log file in English.
  4864.  
  4865.              Maximus's multilingual support can be used to define differ-
  4866.              ent prompts, menus and custom display files for each individ-
  4867.  
  4868.  
  4869.  
  4870.              4. Customization                                           83
  4871.  
  4872.              ual language. Language files can be modified by simply edit-
  4873.              ing the appropriate <langname>.mad file with a text editor.
  4874.  
  4875.              However, a separate set of menus needs to be designed by the
  4876.              SysOp, since the screen display would look odd if the prompts
  4877.              were in German but the menu options were in English. Like-
  4878.              wise, display files should also be changed (using the
  4879.              [iflang] token) to accommodate new languages.
  4880.  
  4881.              The main method for supporting alternate menus and display
  4882.              files is to use the "%Y" external program translation charac-
  4883.              ter. When used in menu and display filenames, the "%Y" se-
  4884.              quence translates to the user's current language number, with
  4885.              0 being the first language defined in language.ctl, 1 being
  4886.              the second language, and so on.
  4887.  
  4888.              The "%Y" sequence can be used in many places, including in
  4889.              the First Menu definition in the system control file, in all
  4890.              Display_Menu options. In addition, the text "+Y" can be used
  4891.              in all Display_File commands. (Note that Display_File re-
  4892.              quires a "plus-Y" instead of a "percent-Y".)
  4893.  
  4894.              For example, if you had the following language statements in
  4895.              language.ctl:
  4896.  
  4897.                 Language  English
  4898.                 Language  Deutsch
  4899.  
  4900.              using a First Menu MAIN %Y statement in the system control
  4901.              file tells Maximus to display MAIN0 for English callers,
  4902.              while MAIN1 will be displayed to German callers.
  4903.  
  4904.              You can also use this methodology for MECCA files. You can
  4905.              either use a Display_File D:\Path\File%Y option to display
  4906.              different physical files for each language, or you can embed
  4907.              the [iflang] token within an individual display file to make
  4908.              decisions based on the current language.
  4909.  
  4910.              By default, Maximus stores a user's language preference in
  4911.              the user file. However, if you want Maximus to prompt the
  4912.              user for a new language during every log-on, you can place
  4913.              the [menu_cmd chg_language] token at the top of welcome.mec.
  4914.  
  4915.  
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.                                                       5. Maximus Subsystems
  4923.  
  4924.  
  4925.              5.1. Waiting for Callers Subsystem
  4926.  
  4927.              Maximus includes internal support for a Waiting for Caller
  4928.              (WFC) subsystem. This subsystem allows Maximus to initialize
  4929.              the modem, wait for a call, answer the phone, and pass con-
  4930.              trol to the main portion of the BBS. The WFC subsystem can be
  4931.              used on all nodes of a system, on selected nodes, or on no
  4932.              nodes. Nodes which do not use the WFC subsystem require an
  4933.              external "front end" program to answer the phone.
  4934.  
  4935.  
  4936.              5.1.1. Starting WFC
  4937.  
  4938.              When starting Maximus, the WFC subsystem is enabled using the
  4939.              "-w" command line switch. Optionally, the "-p" and "-b" pa-
  4940.              rameters can be used to override the COM port and baud rate.
  4941.              If you specify just "-w", WFC starts up using the port and
  4942.              speed defined in the system control file.
  4943.  
  4944.              Before enabling WFC mode, you must ensure that the modem
  4945.              strings in the system control file are configured correctly.
  4946.              The distribution version of Maximus is configured to support
  4947.              most Hayes-compatible modems. However, if the WFC module does
  4948.              not seem to work, you may need to modify certain definitions
  4949.              (such as the Answer and Init strings) to make it perform as
  4950.              expected.
  4951.  
  4952.              In particular, the distribution version of Maximus attempts
  4953.              to use "manual answer mode." Instead of telling the modem to
  4954.              automatically answer the phone when it detects a ring, Maxi-
  4955.              mus will perform the ring checking on its own. This is the
  4956.              preferred method of operation, since the phone is only an-
  4957.              swered when Maximus is ready to accept a call.
  4958.  
  4959.              However, manual phone answering may not be compatible with
  4960.              all modems. If you wish to disable manual answering, change
  4961.              the last part of the Init string to read "S0=1" instead of
  4962.              "S0=0". You must also comment out the Answer string. This in-
  4963.              structs your modem to answer the phone automatically.
  4964.  
  4965.  
  4966.              5.1.2. Screen Display and SysOp Keys
  4967.  
  4968.              After WFC mode initializes, four multicolored windows appear
  4969.              on the screen:
  4970.  
  4971.  
  4972.  
  4973.              5. Maximus Subsystems                                      86
  4974.  
  4975.              The first window, "Status," displays the time until the next
  4976.              system event, the current modem status, the number of calls
  4977.              made to your system (both today and in total), and the name
  4978.              of the last caller on your system.
  4979.  
  4980.              The second window, "Modem Responses," displays a scrolling
  4981.              list of responses from the modem. Maximus uses this window
  4982.              for storing result codes that are sent in response to command
  4983.              strings. (Maximus will automatically filter out any "OK" re-
  4984.              sults, so only meaningful responses will be displayed.)
  4985.  
  4986.              The third window, "Current Activity," displays system log
  4987.              messages as they occur.
  4988.  
  4989.              The fourth window, "SysOp Keys," contains descriptions for
  4990.              all of the keys that can be pressed while in WFC mode.
  4991.  
  4992.              Pressing <alt-k> starts Maximus in local mode. Maximus takes
  4993.              the phone off-hook and commences the normal log-on procedure.
  4994.  
  4995.              Pressing <alt-j> invokes a shell to the DOS or OS/2 command
  4996.              interpreter. Maximus takes the modem off-hook while you are
  4997.              in the shell. You can perform file maintenance, make changes
  4998.              to your batch files, or do other routine operations while in
  4999.              the shell. Type "exit" to return to Maximus.
  5000.  
  5001.              Pressing <alt-x> instructs Maximus to take the system down.
  5002.              Maximus will put the phone off-hook, clear the screen, and
  5003.              exit to your batch file with errorlevel 1.
  5004.  
  5005.              When using the internal WFC subsystem, Maximus also supports
  5006.              external events. External events can be used to run a par-
  5007.              ticular program at a certain time of day, normally by exiting
  5008.              to your batch file with a certain errorlevel.
  5009.  
  5010.              For more information on external events, please see section
  5011.              18.11. For more information on installing WFC, please see
  5012.              section 3.9.
  5013.  
  5014.  
  5015.              5.2. Local File Attaches
  5016.  
  5017.  
  5018.              5.2.1. Description
  5019.  
  5020.              Maximus allows users to create local file attaches. A local
  5021.              file attach is a file that is associated with a message cre-
  5022.              ated by a user.
  5023.  
  5024.              To enable local file attaches, ensure that you have defined
  5025.              an Attach Path keyword in max.ctl. This keyword tells Maximus
  5026.              where to store uploaded files.
  5027.  
  5028.  
  5029.  
  5030.              5. Maximus Subsystems                                      87
  5031.  
  5032.              Next, add the Style Attach  attribute to Squish-format mes-
  5033.              sage areas that you want to use for local file attaches. (The
  5034.              local file attach feature cannot be used with *.MSG areas.)
  5035.  
  5036.              To create a file attach, users simply change to that message
  5037.              area and enter a message. When the cursor is on the attrib-
  5038.              utes field in the message header (which is where the "Pvt"
  5039.              flag is normally displayed), the user can enable the "file
  5040.              attach" flag. (In the English version of Maximus, the A key
  5041.              is used to create a file attach.)
  5042.  
  5043.              After setting the flag, the user can continue to fill out the
  5044.              message header and create the message itself. After the mes-
  5045.              sage has been saved, Maximus will prompt the user to upload
  5046.              the file to be attached to the message.
  5047.  
  5048.              When the transfer is complete, Maximus will compress the at-
  5049.              tached file (using the archiver specified by Attach Archiver
  5050.              in the system control file) and store it in the file attach
  5051.              directory.
  5052.  
  5053.              Later, when the addressee displays the message, the user is
  5054.              given the option to download the file attach. Maximus will
  5055.              then decompress the file and send it to the user.
  5056.  
  5057.              In addition, a user can use the Msg_Download_Attach menu op-
  5058.              tion to display a list of all unreceived files attached to
  5059.              that user.
  5060.  
  5061.  
  5062.              5.2.2. SysOp Configuration
  5063.  
  5064.              The local file attach subsystem is mostly self-maintaining.
  5065.              Using the Kill Attach keyword in the system control file, you
  5066.              can configure Maximus to automatically delete files after
  5067.              they have been received by users.
  5068.  
  5069.              The Message Edit Ask LocalAttach keyword can also be used to
  5070.              control the privilege level required to create a local file
  5071.              attach.
  5072.  
  5073.              If you expect to receive a lot of file attaches in one par-
  5074.              ticular message area, the holding area for the attaches can
  5075.              be overridden on an area-by-area basis using the AttachPath
  5076.              keyword in your message area control file.
  5077.  
  5078.              In addition, the [msg_fileattach] MECCA token can be used to
  5079.              conditionally display text if any unreceived file attaches
  5080.              are waiting for the current user.
  5081.  
  5082.              Finally, Maximus also supports inbound FTS-0001 style
  5083.              "NetMail file attaches" in areas that have both Style Net and
  5084.              Style Attach.
  5085.  
  5086.  
  5087.  
  5088.              5. Maximus Subsystems                                      88
  5089.  
  5090.              When Maximus encounters a message in a NetMail area with the
  5091.              network file attach bit set, it looks in the directory speci-
  5092.              fied by Path Inbound in the system control file. In that di-
  5093.              rectory, it tries to find a file with the name specified on
  5094.              the message's subject line. If that file exists, Maximus
  5095.              treats it as a file attach and sends it to the user.
  5096.  
  5097.        Warni If you add the Style Attach attribute to a NetMail area, you
  5098.          ng! may be compromising the security of your inbound directory.
  5099.              Do not use the local file attach feature in NetMail areas un-
  5100.              less you trust all of the users who have access to that area.
  5101.  
  5102.  
  5103.              5.3. QWK Mail Packer
  5104.  
  5105.              From the Off-Line Reader menu, Maximus allows users to down-
  5106.              load mail to be read off-line. Maximus supports the popular
  5107.              QWK format, so the users can use popular third-party products
  5108.              such as Deluxe2, Qmail, SLMR and OFFLINE to read the packets
  5109.              generated by Maximus.
  5110.  
  5111.              Instructions on configuring the QWK packer are given in sec-
  5112.              tion 4.8.
  5113.  
  5114.  
  5115.              5.3.1. Bulletins, News Files and File Lists
  5116.  
  5117.              QWK packets can include information other than just mail,
  5118.              such as bulletins, file lists and news files. Maximus sup-
  5119.              ports these files in an extremely simple manner: any file
  5120.              placed in the \max\olr directory is automatically placed in
  5121.              all mail packets sent to users.
  5122.  
  5123.              In addition, if a user has unreceived local file attaches,
  5124.              they are automatically placed in the QWK packet.
  5125.  
  5126.              The QWK format defines the names of several standard files
  5127.              that can be included in QWK packets. To use these features,
  5128.              simply place a file in the \max\olr directory with one of the
  5129.              filenames given in Table 5.1:
  5130.  
  5131.              Table 5.1 QWK Packet Filenames
  5132.  
  5133.               Filename       Description
  5134.  
  5135.               hello          Displayed when the off-line reader first
  5136.                              starts up. This is typically the equivalent
  5137.                              of your welcome.bbs screen. This file should
  5138.                              be ANSI only; no AVATAR colors or MECCA
  5139.                              codes are allowed.
  5140.               news           Your BBS news file, equivalent to the
  5141.                              \max\misc\bulletin.bbs file. This is usually
  5142.                              available as an option from the QWK reader's
  5143.  
  5144.  
  5145.  
  5146.              5. Maximus Subsystems                                      89
  5147.  
  5148.                              main menu. This is normally a flat ASCII
  5149.                              file with no graphics.
  5150.               goodbye        Displayed when the reader closes the packet
  5151.                              from your BBS. This file can include ANSI
  5152.                              graphics.
  5153.               blt-1.1        Bulletin file 1. This is usually displayed
  5154.                              as an option on the reader's main menu. In
  5155.                              this case, the file extension is ".1", but
  5156.                              you can use anything from ".1" to ".99" to
  5157.                              provide up to 99 different bulletins.
  5158.               newfiles.dat   This file contains a new files listing for
  5159.                              your BBS. Maximus does not generate this
  5160.                              file for you, but a third-party file list
  5161.                              generator can be configured to generate a
  5162.                              file list and place it in the \max\olr di-
  5163.                              rectory.
  5164.  
  5165.  
  5166.              Again, all of these files are optional. However, since Maxi-
  5167.              mus packs up everything in the \max\olr directory when creat-
  5168.              ing a packet for the remote system, simply placing one of the
  5169.              above files in that directory will cause it to be displayed
  5170.              on the remote side.
  5171.  
  5172.  
  5173.              5.3.2. Message Packing for Remote Users
  5174.  
  5175.              The default Maximus configuration includes an Off-Line Reader
  5176.              menu, but mail can also be packed from the regular message
  5177.              menu. All of the QWK mail packing functionality is built into
  5178.              the Browse command; in fact, the Download command on the Off-
  5179.              Line Reader menu is a simple macro that invokes the Browse
  5180.              command.
  5181.  
  5182.              The default Download command passes the options t n p to
  5183.              Browse. This requests a scan of tagged areas, searching for
  5184.              new messages, and for the messages to be packed in QWK for-
  5185.              mat. Obviously, the flexibility of the Browse command allows
  5186.              many other search operations to be performed. Users can spec-
  5187.              ify a selective download by using the search function
  5188.              (complete with and and or operators). Using Browse, messages
  5189.              can also be packed only from the current area, rather than
  5190.              all tagged message areas.
  5191.  
  5192.              After selecting the Pack option from the Browse menu, Maximus
  5193.              will gather all of the specified messages, display some sta-
  5194.              tistics on the packed messages, and ask the user whether or
  5195.              not the messages should be prepared for download. If so,
  5196.              Maximus will compress the packet with the user's default ar-
  5197.              chiving program, count to ten (giving the user a chance to
  5198.              abort), and send the file using the default transfer proto-
  5199.              col.
  5200.  
  5201.  
  5202.  
  5203.              5. Maximus Subsystems                                      90
  5204.  
  5205.              The Off-Line Reader menu also includes an upload option. This
  5206.              option allows the user to upload a .rep file created by an
  5207.              off-line reader. The .rep file is automatically decompressed,
  5208.              regardless of the archive type or the user's default ar-
  5209.              chiver, and the messages within are placed in the appropriate
  5210.              message area.
  5211.  
  5212.              When processing uploaded messages, the QWK upload command al-
  5213.              ways checks to ensure that the user has enough access to
  5214.              write a message in a given message area. To do this, it first
  5215.              examines the definition for the target message area. If the
  5216.              area has a custom MenuName defined, Maximus will read that
  5217.              menu. Otherwise, Maximus will read the menu called "MESSAGE".
  5218.  
  5219.              Next, Maximus will search that menu for an option of type
  5220.              Msg_Upload. Maximus checks the ACS for that option and com-
  5221.              pares it against the user's access level. If the check suc-
  5222.              ceeds, the user is allowed to upload the message.
  5223.  
  5224.              This access control mechanism has one main implication: un-
  5225.              less you use a specific MenuName definition for all of your
  5226.              message areas, you must have a menu with a name of "MESSAGE,"
  5227.              and that area must have a Msg_Upload option with an ACS that
  5228.              makes it accessible to users.
  5229.  
  5230.  
  5231.              5.3.3. Local Mail Packing
  5232.  
  5233.              The QWK feature can also be used by local callers. After com-
  5234.              pressing a packet for a local user, Maximus will leave the
  5235.              packed QWK file in the off-line reader directory. (By de-
  5236.              fault, the file will be in the \max\olr\node## directory,
  5237.              where ## is the current task number in hexadecimal.)
  5238.  
  5239.              In local mode, if you want to "upload" a .rep packet, select
  5240.              the Upload option from the reader menu. If the caller is lo-
  5241.              cal, Maximus will prompt for the path and filename of the
  5242.              .rep packet. Enter the location of the packet (as created by
  5243.              your off-line reader), and Maximus will decompress and import
  5244.              the messages in that packet.
  5245.  
  5246.  
  5247.              5.3.4. Unattended Mail Packing
  5248.  
  5249.              In conjunction with the "-j" command line parameter, Maximus
  5250.              can compress mail packets for users on a daily basis, without
  5251.              operator or user intervention.
  5252.  
  5253.              At predefined intervals, you can set up a system event (when
  5254.              running in WFC mode) to call Maximus with the "-j" command
  5255.              line parameter. The -j parameter tells Maximus to insert a
  5256.              list of keystrokes in the keyboard buffer, as if the key-
  5257.              strokes were entered by a local user. You can set up these
  5258.  
  5259.  
  5260.  
  5261.              5. Maximus Subsystems                                      91
  5262.  
  5263.              keystrokes so that Maximus will log on as a certain user,
  5264.              execute a download command, log off, and have your batch
  5265.              files copy the created QWK packet to a file area.
  5266.  
  5267.              By doing this, you can pack mail for certain users in ad-
  5268.              vance, or you can use it to save mail for yourself while on
  5269.              vacation. Since the packing process is completely controlled
  5270.              by the keystrokes you specify for the -j parameter, almost
  5271.              any type of mail download is possible.
  5272.  
  5273.              For example, suppose that the following keystrokes are re-
  5274.              quired to move from the bulletin menu (displayed just after
  5275.              the user enters a password) to the off-line reader menu,
  5276.              download a packet, and log off:
  5277.  
  5278.                 n;o;d;y;m;g
  5279.  
  5280.              To instruct Maximus to log on as a specific user and execute
  5281.              these keystrokes, you only need to add the prologue that
  5282.              specifies the user name and password. Consequently, the fol-
  5283.              lowing command sequence can be used to automatically pack
  5284.              mail for a user, assuming the default menu and bulletin file
  5285.              structure.
  5286.  
  5287.                 max "-jJoe User;y;Password;n;o;d;y;m;g"
  5288.  
  5289.        Note! If your log-on sequence includes a "Press ENTER to continue"
  5290.              prompt, you should specify the "|" character where you would
  5291.              normally press the <enter> key.
  5292.  
  5293.              In addition, you can pack mail for multiple users by simply
  5294.              replicating the above line in your batch file. However, your
  5295.              batch file must also copy the QWK packet from the
  5296.              \max\olr\node## directory into a safe place after each mail
  5297.              pack.
  5298.  
  5299.  
  5300.              5.3.5. NetMail Messages
  5301.  
  5302.              The QWK format was not designed with NetMail messages in
  5303.              mind, so users must follow a special convention when reading
  5304.              and replying to NetMail messages. When downloading messages
  5305.              from a NetMail area, the first line of each message will look
  5306.              like this:
  5307.  
  5308.                 From: <addr>
  5309.  
  5310.              where <addr> is the network address of the message sender.
  5311.              Since there is no place in the QWK header to store the true
  5312.              message origination address, Maximus places that information
  5313.              in the message body instead.
  5314.  
  5315.  
  5316.  
  5317.              5. Maximus Subsystems                                      92
  5318.  
  5319.              When creating or replying to a NetMail message, Maximus ex-
  5320.              pects to find a "To: <addr>" line as the first line in the
  5321.              message body. For example, to send a NetMail message to the
  5322.              address 1:123/456, the first line of the message must look
  5323.              like this:
  5324.  
  5325.                 To: 1:123/456
  5326.  
  5327.              The "To:" header will be stripped before the message is writ-
  5328.              ten to the Maximus message base, so your QWK messages will
  5329.              look like normal messages to everyone else.
  5330.  
  5331.              When replying to a message, there is an easy way to set the
  5332.              destination address; simply quote the original message and
  5333.              change the "From:" line to a "To:" line (after removing any
  5334.              quoting marks). This ensures that the destination address is
  5335.              correct, and Maximus will ensure that your reply is sent to
  5336.              the intended destination.
  5337.  
  5338.  
  5339.              5.4. RIPscrip Support
  5340.  
  5341.              Maximus includes internal support for RIPscrip graphics com-
  5342.              mands. RIPscrip is a terminal protocol designed by TeleGrafix
  5343.              Communications, Inc. The RIPscrip protocol includes facili-
  5344.              ties for displaying buttons, icons and various other forms of
  5345.              graphics over a serial line. RIPscrip also allows the remote
  5346.              user to use a mouse to access system commands and features.
  5347.  
  5348.              The distribution version of Maximus comes with support for
  5349.              RIPscrip graphics, including a number of sample screens, but
  5350.              this support must be enabled before it can be selected by us-
  5351.              ers. To enable RIPscrip graphics support, set the Min RIP
  5352.              Baud definition (in the system control file) to the minimum
  5353.              speed that you require for users to be able to view RIPscrip
  5354.              graphics. (In most cases, setting this to 2400 or 9600 is
  5355.              usually a good idea.)
  5356.  
  5357.              After RIPscrip support is enabled, users will be able to se-
  5358.              lect RIPscrip graphics using the Chg_RIP command on the
  5359.              Change Setup menu. In addition, new users will be prompted
  5360.              for RIPscrip graphics support when they log on.
  5361.  
  5362.              Maximus does not display RIPscrip graphics on the SysOp
  5363.              screen. (In fact, the local output routines include a "smart"
  5364.              filter that automatically strip out RIPscrip graphics se-
  5365.              quences from local output.)
  5366.  
  5367.              However, Maximus includes the following RIPscrip-specific
  5368.              features:
  5369.  
  5370.              *  When instructed to display a .bbs file, Maximus will first
  5371.                 look for a file with a .rbs extension. To add a RIPscrip-
  5372.  
  5373.  
  5374.  
  5375.              5. Maximus Subsystems                                      93
  5376.  
  5377.                 specific version of one of your system display files, sim-
  5378.                 ply create the RIPscrip file using the same base name as
  5379.                 the standard display file, but use a .rbs extension instead
  5380.                 of .bbs.
  5381.  
  5382.                 To create .rbs files, you have one of two options:
  5383.  
  5384.                 1.Use a third-party RIPscrip editor to create the .rbs
  5385.                   file directly.
  5386.  
  5387.                 2.Use MECCA to compile a .mer file into a .rbs file. In
  5388.                   addition to the standard .mec extension, MECCA also rec-
  5389.                   ognizes .mer files as containing MECCA source. You can
  5390.                   embed MECCA commands inside RIPscrip graphics in this
  5391.                   manner.
  5392.  
  5393.              *  If you decide not to create separate .rbs files, small
  5394.                 RIPscrip sequences can still be included in standard dis-
  5395.                 play files. To mark a section of a MECCA file so that it is
  5396.                 only displayed to callers with RIPscrip support, use the
  5397.                 [rip] and [endrip] tokens around the RIPscrip-specific
  5398.                 text.
  5399.  
  5400.              *  Similarly, the [norip] and [endrip] tokens can be used to
  5401.                 mark a section of a MECCA file that is only displayed to
  5402.                 callers who do not support RIPscrip graphics.
  5403.  
  5404.              *  With RIPscrip enabled, many of the system prompts are dis-
  5405.                 played using RIPscrip-specific buttons and features.
  5406.  
  5407.              *  An alternate set of RIPscrip strings are used in the lan-
  5408.                 guage file. The standard english.mad language file is con-
  5409.                 figured to return different display strings for some system
  5410.                 display fields if the user supports RIPscrip graphics. This
  5411.                 allows the SysOp to define one set of responses for text-
  5412.                 based callers and a second set of responses for RIPscrip
  5413.                 callers.
  5414.  
  5415.              *  The full-screen editor and full-screen reader are RIPscrip-
  5416.                 aware. The message header is drawn using RIPscrip commands,
  5417.                 and the header remains on the screen even when entering the
  5418.                 message editor.
  5419.  
  5420.              *  Maximus automatically parses the "set text window" and "set
  5421.                 font" RIPscrip sequences. It uses this information to ad-
  5422.                 just the user's virtual terminal size, control the "More
  5423.                 [Y,n,=]?" prompts, size the full-screen editor, and so on.
  5424.  
  5425.              *  A number of RIPscrip-specific display files are included
  5426.                 with the standard distribution.
  5427.  
  5428.              *  Maximus can automatically send RIPscrip scene and icon
  5429.                 files to the remote user. The MECCA [ripsend] and
  5430.  
  5431.  
  5432.  
  5433.              5. Maximus Subsystems                                      94
  5434.  
  5435.                 [riphasfile] tokens can be used to conditionally send a set
  5436.                 of scene or icon files to the remote user. The equivalent
  5437.                 MEX functions, rip_send and rip_hasfile, can also be used
  5438.                 for this task.
  5439.  
  5440.              *  When a user logs on, if that user's profile indicates that
  5441.                 RIPscrip graphics are supported, Maximus will automatically
  5442.                 send a query to the user's terminal program. If the termi-
  5443.                 nal program does not report that it supports RIPscrip
  5444.                 graphics, Maximus will display a warning to the user and
  5445.                 offer to disable RIPscrip support.
  5446.  
  5447.              *  Maximus keeps track of a "RIP path." This path is where
  5448.                 Maximus looks for icon and scene files that are referenced
  5449.                 by the [ripsend] and [ripdisplay] tokens. This path can be
  5450.                 changed using the [rippath] MECCA token. (To implement mul-
  5451.                 tilingual RIPscrip support, you may want to have a separate
  5452.                 directory of RIPscrip files for each supported language.)
  5453.  
  5454.              *  For consistency, when RIPscrip graphics are selected, Maxi-
  5455.                 mus forces the user to enable hotkeys, the full-screen
  5456.                 reader and screen clears.
  5457.  
  5458.              *  Menu options can be made available only to RIPscrip callers
  5459.                 by using the RIP modifier in front of a menu option. Simi-
  5460.                 larly, menu options can be made available only to callers
  5461.                 without RIPscrip support by using the NoRIP modifier.
  5462.  
  5463.              *  If a user enables RIPscrip support after failing the inter-
  5464.                 nal RIPscrip-detection test, Maximus will note this in the
  5465.                 system log file. When Maximus queries the remote  system
  5466.                 and fails to obtain an intelligent response, Maximus will
  5467.                 retry the command up to three times before aborting. At
  5468.                 this point, Maximus assumes that the caller enabled
  5469.                 RIPscrip graphics in error, so RIPscrip graphics are auto-
  5470.                 matically disabled and Maximus displays a warning to the
  5471.                 user.
  5472.  
  5473.  
  5474.              5.5. User Expiration and Subscriptions
  5475.  
  5476.              Maximus includes an internal user subscription and expiry
  5477.              subsystem. Callers can be set to expire based on the current
  5478.              date, or also based on system time used (in minutes). When a
  5479.              caller expires, Maximus can optionally demote that caller to
  5480.              a lower privilege level, hang up, or delete the user's ac-
  5481.              count.
  5482.  
  5483.              To access the user subscription system, start up the Maximus
  5484.              user editor by running "max -uq".
  5485.  
  5486.  
  5487.  
  5488.              5. Maximus Subsystems                                      95
  5489.  
  5490.              To set up a user subscription, first press the E key to se-
  5491.              lect the expiry menu. Next, press E again to set the "expire
  5492.              by" method:
  5493.  
  5494.              If you want the user to expire after a certain date, select
  5495.              D. If you want the user to expire after having used a certain
  5496.              number of minutes on the system, select M. If you want to
  5497.              disable the subscription system, select N.
  5498.  
  5499.              Next, press E again to go back to the expiry menu, and press
  5500.              A to select an expiry action. This field controls how Maximus
  5501.              treats the user when the subscription expires. If you want
  5502.              Maximus to hang up and delete the user's account, select A.
  5503.              To have Maximus demote the user to a lower privilege level,
  5504.              select D and enter the new privilege level for the user. If
  5505.              you do not want Maximus to do anything when the subscription
  5506.              expires, select N.
  5507.  
  5508.              Finally, press E one last time to go back to the expiry menu,
  5509.              and press D to select the date/time for the user expiration.
  5510.              If you previously selected date in the "expire by" field, en-
  5511.              ter the user's expiry date here. Otherwise, enter the number
  5512.              of on-line minutes to be credited to the user.
  5513.  
  5514.              After setting up the expiry controls for a user, the sub-
  5515.              scription system is completely self-maintaining. When a user
  5516.              expires, the user's privilege level will be modified accord-
  5517.              ingly as soon as the user logs in.
  5518.  
  5519.              In addition, when a user expires using the "by date" expira-
  5520.              tion method, the file \max\misc\xpdate.bbs is shown. Simi-
  5521.              larly, when a user expires due to running out of on-line min-
  5522.              utes, Maximus will display the \max\misc\xptime.bbs file.
  5523.  
  5524.  
  5525.              5.6. Message Tracking System
  5526.  
  5527.  
  5528.              5.6.1. Introduction
  5529.  
  5530.              Maximus includes an internal Message Tracking System (MTS).
  5531.              This feature makes it easy for organizations to ensure that
  5532.              technical support queries are answered on a timely basis, and
  5533.              it provides audit trails for technical support queries. MTS
  5534.              is only supported for message areas stored in the Squish mes-
  5535.              sage format.
  5536.  
  5537.              Message areas can be designated as MTS areas, which means
  5538.              that Maximus will automatically place all messages entered
  5539.              into those areas in the MTS database. Whenever a message is
  5540.              created in an MTS area, Maximus will automatically set a de-
  5541.              fault message priority, status, and message owner. These MTS
  5542.  
  5543.  
  5544.  
  5545.              5. Maximus Subsystems                                      96
  5546.  
  5547.              fields are hidden from normal users, but they can be viewed
  5548.              and modified by technical support personnel.
  5549.  
  5550.              The owner field is used to "assign" a message to a specific
  5551.              support representative. After the representative assumes own-
  5552.              ership of a message, it becomes that representative's respon-
  5553.              sibility to ensure that the message is handled appropriately.
  5554.  
  5555.              MTS uses relational database links to store owner informa-
  5556.              tion, thereby making it easy to perform mass ownership trans-
  5557.              fers. For example, if a particular representative goes on va-
  5558.              cation for a number of weeks, a single database entry can be
  5559.              changed by the MTS administrator to assign all of the repre-
  5560.              sentative's messages to another user. The change can then be
  5561.              reversed when the original representative returns.
  5562.  
  5563.              Maximus handles this by assigning a four-character "alias" to
  5564.              each representative (or in MTS terminology, to each modera-
  5565.              tor). A message is actually owned by an specific alias, which
  5566.              is in turn linked to a moderator (representative).
  5567.  
  5568.              In terms of manipulating MTS data, the system works best when
  5569.              the moderator can log onto Maximus to read and reply to mes-
  5570.              sages. After a moderator replies to a message, Maximus pro-
  5571.              vides an option that allows the moderator to change the
  5572.              status of that message, if necessary. The Track menu option
  5573.              can also be used to modify the message's owner and priority,
  5574.              manually insert messages in the tracking database, generate
  5575.              reports, and perform database administration functions.
  5576.  
  5577.              MTS also works with off-line QWK mail readers. QWK support is
  5578.              implemented by placing a small template at the beginning of
  5579.              each tracked message in a .qwk packet. (This template is only
  5580.              placed in the QWK message if the user's access level is at
  5581.              least equal to the privilege level specified by Track View.)
  5582.  
  5583.              To modify the status of a message from a QWK reader, the off-
  5584.              line database moderator can simply quote that template in the
  5585.              reply message, marking an "X" in the appropriate box with a
  5586.              standard text editor. Maximus will automatically strip the
  5587.              template from the uploaded message and make the required
  5588.              changes to the message database.
  5589.  
  5590.              MTS can also be used as a central tracking system for mes-
  5591.              sages created on remote systems. Even if a message was en-
  5592.              tered on another system and transmitted as an EchoMail mes-
  5593.              sage, when that message arrives on a Maximus system that runs
  5594.              MTS, it will be entered in the database when the message is
  5595.              accessed or read by any user. (Distributed tracking databases
  5596.              are not supported, since all of the tracking files must be
  5597.              stored on one system. However, tracking of distributed mes-
  5598.              sage bases is supported by placing all imported messages into
  5599.              the local tracking database.)
  5600.  
  5601.  
  5602.  
  5603.              5. Maximus Subsystems                                      97
  5604.  
  5605.              By default, Maximus will add a message to the tracking data-
  5606.              base if:
  5607.  
  5608.                 1.the message area is declared with the "Audit" keyword,
  5609.                 2.the message area has a default owner assigned, and
  5610.                 3.the user entering the message is not the default owner.
  5611.  
  5612.              MTS also allows the moderators to generate reports based on
  5613.              tracking information. Reports can be generated on-line, writ-
  5614.              ten to a file, or even included in a QWK packet. The reports
  5615.              can be configured so that only a certain subset of tracked
  5616.              messages are displayed; for example, a moderator can easily
  5617.              request a report of all "Open" or "Working" messages, with a
  5618.              priority of "Urgent" or "Critical," owned by a specific mod-
  5619.              erators, across all of the message areas on the system.
  5620.  
  5621.  
  5622.              5.6.2. Information Stored by MTS
  5623.  
  5624.              The Message Tracking System stores the following information
  5625.              for each message in its database:
  5626.  
  5627.              *  The message owner, stored as a four-character alias.
  5628.  
  5629.              *  The message status. The status field contains one of the
  5630.                 following values:
  5631.  
  5632.                 * New
  5633.                 * Open
  5634.                 * Working
  5635.                 * Closed
  5636.  
  5637.                 This field allows the moderators and the database adminis-
  5638.                 trator to assess the current status of a problem report.
  5639.  
  5640.              *  The message priority This field contains one of the follow-
  5641.                 ing priority levels:
  5642.  
  5643.                 * Notify
  5644.                 * Low
  5645.                 * Normal
  5646.                 * Urgent
  5647.                 * Critical
  5648.  
  5649.                 This field can be used to assign a relative importance to a
  5650.                 particular message.
  5651.  
  5652.              *  The message audit trail. The audit trail is actually stored
  5653.                 as part of the message body. The Msg_Kludges menu option
  5654.                 can be used to toggle display of the audit trail.
  5655.  
  5656.  
  5657.  
  5658.              5. Maximus Subsystems                                      98
  5659.  
  5660.              *  A message comment. This is also stored as part of the mes-
  5661.                 sage body, but it can be examined or modified using the
  5662.                 Modify command on the Track menu.
  5663.  
  5664.              The tracking mechanism is completely transparent to the end
  5665.              user. The MTS data can be displayed in the message header
  5666.              when a message is shown, but this information is only avail-
  5667.              able to the MTS moderators.
  5668.  
  5669.  
  5670.              5.6.3. Configuration
  5671.  
  5672.              This section describes the settings and definitions that are
  5673.              required to enable support for MTS:
  5674.  
  5675.              To use MTS, the keywords listed in Table 5.2 must be present
  5676.              in the system control file. Please see section 18.2.4 for
  5677.              more information on these keywords:
  5678.  
  5679.              Table 5.2 MTS System Keywords
  5680.  
  5681.               Keyword        Description
  5682.  
  5683.               Track Base     Specifies the base path and filename for
  5684.                              the MTS database.
  5685.               Track View     An ACS that controls who can view tracking
  5686.                              information in messages.
  5687.               Track Modify   An ACS that controls who is allowed to ac-
  5688.                              cess the Track/Admin menu and modify track-
  5689.                              ing information.
  5690.               Track Exclude  An optional file listing users whose mes-
  5691.                              sages are to be excluded from the tracking
  5692.                              database.
  5693.  
  5694.  
  5695.              To configure a message area to support MTS, the keywords
  5696.              listed in Table 5.3 must be added to the definition in the
  5697.              message area control file. Please see section 18.6 for more
  5698.              information on these keywords.
  5699.  
  5700.              Table 5.3 MTS Message Area Keywords
  5701.  
  5702.               Keyword          Description
  5703.  
  5704.               Style Audit      Indicates that the area supports MTS mes-
  5705.                                sages.
  5706.               Owner <alias>    Indicates the alias of the default owner
  5707.                                for the area. See the following section
  5708.                                for information on creating modera-
  5709.                                tor/alias links.
  5710.  
  5711.  
  5712.  
  5713.              5. Maximus Subsystems                                      99
  5714.  
  5715.              5.6.4. Using MTS
  5716.  
  5717.              Administrators can access the MTS database using the
  5718.              Msg_Track command (which is normally the "%" option on the
  5719.              message menu).
  5720.  
  5721.              The main MTS menu contains the options shown below in Table
  5722.              5.4:
  5723.  
  5724.              Table 5.4 MTS Main Menu
  5725.  
  5726.               Command        Description
  5727.  
  5728.               Insert         Manually inserts a message into the MTS
  5729.                              database
  5730.               Modify         Modify the tracking information for a spe-
  5731.                              cific message
  5732.               Report         Display a report based on messages in the
  5733.                              MTS database
  5734.               Administration Change area and owner links or remove mes-
  5735.                              sages.
  5736.  
  5737.  
  5738.  
  5739.              5.6.4.1. Insert
  5740.  
  5741.              The Insert command allows a moderator to add an existing mes-
  5742.              sage to the tracking database. Normally, this command need
  5743.              not be used, since messages in MTS areas are automatically
  5744.              added to the tracking database when they are created.
  5745.  
  5746.              The Insert command prompts the user to enter the message num-
  5747.              ber of the message to add, plus the new owner for the mes-
  5748.              sage. The owner can be any of the existing moderators in the
  5749.              tracking database. The new message is assigned a priority of
  5750.              normal and a status of new.
  5751.  
  5752.  
  5753.              5.6.4.2. Modify
  5754.  
  5755.              The Modify command allows a moderator to change the status of
  5756.              an existing message. This command allows moderators to modify
  5757.              the message's owner, status, priority and message comment.
  5758.              All changes made to the message are added to the audit trail.
  5759.  
  5760.              Every time a moderator replies to a message that he/she owns,
  5761.              Maximus will prompt the moderator for a new message status.
  5762.              Almost all status changes occur when a moderator replies to a
  5763.              message, so most moderators will not need to use this command
  5764.              on a frequent basis.
  5765.  
  5766.  
  5767.  
  5768.              5. Maximus Subsystems                                     100
  5769.  
  5770.              5.6.4.3. Report
  5771.  
  5772.              The Report command allows a moderator to generate a report of
  5773.              messages in the tracking database. The moderator can select a
  5774.              set of criteria for displaying information from the database,
  5775.              including message area, status, priority and owner.
  5776.  
  5777.              The tracking report contains a list of each message that
  5778.              matches the specified criteria, including the tracking iden-
  5779.              tifier of each message, the date it was placed in the track-
  5780.              ing system, the message status, priority and owner, and the
  5781.              location of the message (area and message number).
  5782.  
  5783.  
  5784.              5.6.4.4. Administration
  5785.  
  5786.              The administration menu contains options for tasks which do
  5787.              not normally need to be performed on a daily basis. Modera-
  5788.              tors must have a privilege level of at least Track Modify to
  5789.              access the administration menu.
  5790.  
  5791.              Owner/alias links. This menu allows the owner/area links to
  5792.              be created or modified. In the tracking database, the message
  5793.              owner is recorded as a four-letter abbreviation. The
  5794.              owner/alias link is used to associate a specific moderator
  5795.              with an abbreviation.
  5796.  
  5797.              Use the Add command to provide a four-character alias, fol-
  5798.              lowed by the name of the owner to associate with that alias.
  5799.  
  5800.              Use the Delete option to remove an existing owner/alias link.
  5801.  
  5802.              Use the List option to list existing owner/alias links.
  5803.  
  5804.              Area/owner links. This menu allows the default area owner
  5805.              links to be modified. Although SILT will automatically update
  5806.              these entries based on the Owner keyword in the message area
  5807.              definition, this menu can be used to manually add, delete, or
  5808.              list the current owner/area links.
  5809.  
  5810.              The area/owner links control the default owner for newly-
  5811.              created messages in the specified area. Unless an area has a
  5812.              default owner, messages entered in the area will not be added
  5813.              to the MTS database.
  5814.  
  5815.              Remove message. This option removes a message from the MTS
  5816.              database. The user is prompted to enter a message number, and
  5817.              the message matching that number is then removed from the da-
  5818.              tabase.
  5819.  
  5820.  
  5821.  
  5822.              5. Maximus Subsystems                                     101
  5823.  
  5824.              5.6.5. QWK Message Processing
  5825.  
  5826.              In addition to manipulating tracking data while on-line, MTS
  5827.              can also be accessed through the QWK mail packer. When Maxi-
  5828.              mus packs a message that is stored in the MTS database, it
  5829.              adds a special "tracking header" and "tracking footer" to the
  5830.              top and bottom of the message. A user's privilege level must
  5831.              satisfy the Track View ACS in order to be able to see this
  5832.              information.
  5833.  
  5834.              The first header line, ACTRACK, contains the MTS identifier
  5835.              for the message being downloaded. This is a used as a unique
  5836.              identifier in the MTS database.
  5837.  
  5838.              The second header, STATUS, contains the status of the mes-
  5839.              sage. The curly braces, ("{ }") indicate the current status
  5840.              of the message. The other fields have square brackets ("[ ]")
  5841.              to indicate the other possible settings for the message
  5842.              status.
  5843.  
  5844.              In the message trailer, the OWNER line contains the four-
  5845.              letter identifier for the owner of the message.
  5846.  
  5847.              The priority line, PRTY, indicates the current priority of
  5848.              the message. As before, the braces indicate the current pri-
  5849.              ority, and the square brackets indicate the possible priority
  5850.              selections.
  5851.  
  5852.              The comment line is a one-line field that the moderators can
  5853.              use to assign a comment to each message. The comment can be
  5854.              as long as will fit inside the square brackets.
  5855.  
  5856.              The QWK moderator can modify these headers and footers in a
  5857.              reply message, causing Maximus to change the status of the
  5858.              message or perform some other operation when the .rep packet
  5859.              is uploaded. To communicate a change back to Maximus, the
  5860.              moderator must reply to the message, using the off-line
  5861.              reader's quoting feature to copy the tracking lines into the
  5862.              reply.
  5863.  
  5864.              The ACTRACK line must always be quoted, since it gives Maxi-
  5865.              mus the information that it needs to link the reply with the
  5866.              original message.
  5867.  
  5868.              Following the ACTRACK line, any of the other tracking lines
  5869.              can be quoted (and in any order). To change the status or
  5870.              priority of a message, simply put an "x" inside the set of
  5871.              square brackets for the desired status/priority. Do not add
  5872.              or delete any characters from the line; simply quote it ver-
  5873.              batim and use overtype mode for making any necessary modifi-
  5874.              cations.
  5875.  
  5876.  
  5877.  
  5878.              5. Maximus Subsystems                                     102
  5879.  
  5880.              The owner and comment lines can be changed by overtyping in a
  5881.              similar manner.
  5882.  
  5883.              If an "x" is placed in the "Discard Reply Text" checkbox,
  5884.              Maximus will throw away the reply message after processing
  5885.              the tracking database changes. This should be used if a mod-
  5886.              erator does not wish to post a message but still wants to
  5887.              make a change to the message status.
  5888.  
  5889.              When saving a message to disk, Maximus will automatically
  5890.              strip out the tracking lines (and the preceding quote marks).
  5891.  
  5892.              The tracking reply messages are uploaded normally, just like
  5893.              any other .rep packets. Upon upload, Maximus will display a
  5894.              few status lines indicating the changes that it is making to
  5895.              the tracking database.
  5896.  
  5897.  
  5898.              5.6.6. EchoMail support
  5899.  
  5900.              Maximus also supports tracking of EchoMail messages. Messages
  5901.              can be imported into the tracking database by a standard
  5902.              EchoMail tosser, and Maximus will automatically add the mes-
  5903.              sages to the tracking database as they are read by users.
  5904.  
  5905.              Maximus will automatically add remotely-entered messages
  5906.              which meet the following criteria:
  5907.  
  5908.                 1.The message area is already configured to add locally-
  5909.                   entered messages, including the Style Audit and Owner
  5910.                   definitions.
  5911.                 2.The message does not contain an "ACGHOST" kludge line.
  5912.                 3.The "local" attribute is not set.
  5913.                 4.The "date written" field is not the same as the "date
  5914.                   arrival" field.
  5915.  
  5916.  
  5917.              5.6.7. Audit Trails
  5918.  
  5919.              Maximus keeps an audit trail for all messages in the tracking
  5920.              database. This audit trail takes the form of timestamped en-
  5921.              tries which are added to the bottom of each message. An entry
  5922.              is added to the audit trail when:
  5923.  
  5924.                 1.the message is entered in the database,
  5925.                 2.the message is removed from the database,
  5926.                 3.the message status is changed,
  5927.                 4.the message priority is changed,
  5928.                 5.the message owner is changed, or
  5929.                 6.the message comment is changed.
  5930.  
  5931.              To view the auditing information on-line, use the "!" key
  5932.              (Msg_Kludges) to toggle the display of auditing information
  5933.  
  5934.  
  5935.  
  5936.              5. Maximus Subsystems                                     103
  5937.  
  5938.              and other kludge lines. Auditing information is also avail-
  5939.              able to off-line reader users whose privilege level is at
  5940.              least that given by the Message Show Ctl_A definition in the
  5941.              system control file.
  5942.  
  5943.  
  5944.              5.6.8. Import/Export Facilities
  5945.  
  5946.              MTS provides facilities for exporting and importing the
  5947.              tracking database to a delimited ASCII file.
  5948.  
  5949.              The TRACKEXP program is used to export the tracking database.
  5950.              It creates the files shown below in Table 5.5:
  5951.  
  5952.              Table 5.5 Tracking Export Data Files
  5953.  
  5954.               Filename      Description
  5955.  
  5956.               trkmsg.dbf    Message ID / status / owner / location
  5957.               trkarea.dbf   Default area / owner links
  5958.               trkown.dbf    Owner / alias links
  5959.  
  5960.  
  5961.              The format of trkmsg.dbf is given below. The system creates
  5962.              one line per message. All fields are enclosed in double
  5963.              quotes:
  5964.  
  5965.                 <id>,<owner>,<area>,<msgnum>,<status>,<priority>,
  5966.                   <date>,<time>
  5967.  
  5968.                 <id> is the 16-character tracking ID for the message in
  5969.                 question.
  5970.  
  5971.                 <owner> is the four-character alias for the owner of the
  5972.                 message. This is used as a link to the trkown.dbf database.
  5973.  
  5974.                 <area> is the full area name in which the message is
  5975.                 stored.
  5976.  
  5977.                 <msgnum> is the unique message identifier representing the
  5978.                 tracked message.
  5979.  
  5980.                 <status> is the status of the message. (0=New; 1=Open;
  5981.                 2=Working; 3=Closed.)
  5982.  
  5983.                 <priority> is the priority of the message. (0=Notification;
  5984.                 1=Low; 2=Normal; 3=Urgent; 4=Critical.)
  5985.  
  5986.                 <date> is the actual date of the message, in mm/dd/yy for-
  5987.                 mat.
  5988.  
  5989.                 <time> is the actual time of the message, in hh:mm:ss for-
  5990.                 mat.
  5991.  
  5992.  
  5993.  
  5994.              5. Maximus Subsystems                                     104
  5995.  
  5996.              The format of trkarea.dbf is as follows:
  5997.  
  5998.                 <area>,<owner>
  5999.  
  6000.                 <area> is the full name of the message area.
  6001.  
  6002.                 <owner> is the four-character alias for the area's default
  6003.                 owner. This is used as a link to the trkown.dbf database.
  6004.  
  6005.              The format of trkown.dbf is as follows:
  6006.  
  6007.                 <owner>,<name>
  6008.  
  6009.                 <owner> is the four-character alias for the owner.
  6010.  
  6011.                 <name> is the full ASCII username of the owner.
  6012.  
  6013.              TRACKIMP can also be used to import data from .dbf files back
  6014.              into the tracking database.
  6015.  
  6016.              TRACKIMP reads files with the same names and same formats as
  6017.              generated by TRACKEXP. In addition, TRACKIMP will only import
  6018.              new messages; it will display an error message if you try to
  6019.              import a message with an <id> that already exists in the da-
  6020.              tabase.
  6021.  
  6022.              Consequently, if you want to export the tracking database,
  6023.              make changes, and re-import the resulting information, you
  6024.              must delete the current tracking database before importing
  6025.              the .dbf files again. To do this, remove the trk*.db and
  6026.              trk*.i?? files from the \max directory before starting the
  6027.              import.
  6028.  
  6029.  
  6030.              5.6.9. Limitations
  6031.  
  6032.              Only Squish message areas are supported by MTS. *.MSG areas
  6033.              do not provide any facility for assigning a unique number to
  6034.              a message, so renumbering messages in a *.MSG area would in-
  6035.              validate all of the links in the tracking database. For this
  6036.              reason, *.MSG tracking is not supported.
  6037.  
  6038.  
  6039.  
  6040.  
  6041.  
  6042.  
  6043.  
  6044.  
  6045.                                                        6. External Programs
  6046.  
  6047.              Maximus offers a large number of internal features, but occa-
  6048.              sionally, you may wish to execute external programs while a
  6049.              user is on-line. Maximus can run almost all types of external
  6050.              programs, from customized file transfer protocols to "door"
  6051.              programs written for other types of BBS software.
  6052.  
  6053.              Maximus can be configured to run an external program from a
  6054.              menu option, from a MECCA file, or even from a MEX program.
  6055.  
  6056.  
  6057.              6.1. Execution Methods
  6058.  
  6059.              Maximus supports three primary methods for running external
  6060.              programs. You should use the execution method that corre-
  6061.              sponds to the type of program that you want to run.
  6062.  
  6063.              Table 6.1 describes the benefits of the different execution
  6064.              methods. (When in doubt, use the "DOS" method.)
  6065.  
  6066.              Table 6.1 External Program Types
  6067.  
  6068.               Type        Description
  6069.  
  6070.               DOS         This is the so-called "standard" execution
  6071.                           method for both DOS and OS/2 systems. Maximus
  6072.                           loads a second copy of the command processor
  6073.                           (either command.com for DOS or cmd.exe for
  6074.                           OS/2) and tells it to run the specified pro-
  6075.                           gram.
  6076.  
  6077.                           This is the only way to run a .bat or .cmd
  6078.                           file as an external program. This is also the
  6079.                           only way to execute internal command processor
  6080.                           commands, such as DIR, TYPE, CHDIR, and so on.
  6081.  
  6082.                           Maximus will automatically search for the pro-
  6083.                           gram on the current path.
  6084.  
  6085.                           In the DOS version, an extra copy of com-
  6086.                           mand.com must be loaded, which will increase
  6087.                           the memory requirements for your program by
  6088.                           roughly 5k.
  6089.  
  6090.                           This is the method used by the Xtern_DOS menu
  6091.                           option and the [xtern_dos] MECCA token. The
  6092.                           MEX shell function can also be configured to
  6093.                           perform a DOS exit.
  6094.  
  6095.  
  6096.  
  6097.              6. External Programs                                      106
  6098.  
  6099.               Run         This execution method is similar to the DOS
  6100.                           method, except that the command interpreter is
  6101.                           not loaded. In general, programs executed with
  6102.                           the Run method will load slightly faster than
  6103.                           with the DOS method.
  6104.  
  6105.                           However, you cannot load .bat or .cmd files
  6106.                           with this method.
  6107.  
  6108.                           This is the method used by the Xtern_Run menu
  6109.                           option and the [xtern_run] MECCA token. The
  6110.                           MEX shell function can also be configured to
  6111.                           perform a Run exit.
  6112.  
  6113.               Errorlevel  This exit type is only supported under DOS.
  6114.                           This tells Maximus to exit completely from
  6115.                           memory and return to the calling batch file or
  6116.                           program.
  6117.  
  6118.                           This method is very slow because the entire
  6119.                           Maximus image must be reloaded after the ex-
  6120.                           ternal program has finished executing. In ad-
  6121.                           dition, the transient portion of command.com
  6122.                           must also be reloaded.
  6123.  
  6124.                           This is the method used by the Xtern_Erlvl
  6125.                           menu option and the [xtern_erlvl] MECCA token.
  6126.  
  6127.                           See section 6.3 for more information on error-
  6128.                           level batch files.
  6129.  
  6130.  
  6131.  
  6132.  
  6133.              6.2. Swapping
  6134.  
  6135.          DOS By enabling the Swap keyword in the system control file,
  6136.        only! Maximus can swap itself to EMS, XMS or disk when executing a
  6137.              program by the DOS or Run execution methods. When Maximus is
  6138.              swapped out, it will occupy less than 3k of conventional mem-
  6139.              ory.
  6140.  
  6141.              Swapping using the DOS or Run methods is generally preferred
  6142.              to using the Errorlevel method. Swapping is also much faster
  6143.              than using the Errorlevel method if your system has free EMS
  6144.              or XMS memory.
  6145.  
  6146.  
  6147.              6.3. Errorlevel Batch Files
  6148.  
  6149.              When exiting using the Errorlevel method, Maximus can create
  6150.              an optional batch file to pass command line parameters to an
  6151.              external program.
  6152.  
  6153.  
  6154.  
  6155.              6. External Programs                                      107
  6156.  
  6157.              To create an errorlevel batch file, you must specify an er-
  6158.              rorlevel to be used for the exit, in addition to the name of
  6159.              the program to run (including any optional parameters). Con-
  6160.              sequently, an errorlevel exit looks very similar to a DOS or
  6161.              Run exit, except that an errorlevel is added to the beginning
  6162.              of the command to be executed.
  6163.  
  6164.              When Maximus encounters an argument after the errorlevel, it
  6165.              will write a file called errorl##.bat in \max directory,
  6166.              where ## is the current node number in hexadecimal. (In the
  6167.              case of node 0, the file is called errorlvl.bat.) Maximus
  6168.              will place the argument string specified in the Xtern_Erlvl
  6169.              exit into that batch file.
  6170.  
  6171.              After Maximus exits, your runbbs.bat file can trap the error-
  6172.              level and use a "call errorl##.bat" command to execute the
  6173.              external program.
  6174.  
  6175.              For example, given the following menu command:
  6176.  
  6177.                 Xtern_Erlvl  65_Mydoor.Exe_/p%p_/b%b  Demoted "Door"
  6178.  
  6179.              When Maximus executes this menu option, it will create an er-
  6180.              rorl##.bat file (with ## replaced by the node number) that
  6181.              contains:
  6182.  
  6183.                 Mydoor.Exe /p1 /b9600
  6184.  
  6185.              Your batch file should check for errorlevel 65, issue a "call
  6186.              errorl##.bat", and then reload Maximus. The procedure for re-
  6187.              loading Maximus after an errorlevel exit is described in the
  6188.              following section.
  6189.  
  6190.  
  6191.              6.4. Restarting After Errorlevel Exit
  6192.  
  6193.              After executing an external program using the Errorlevel exit
  6194.              method, Maximus can restart itself exactly where it left off.
  6195.              To users, it will appear as if Maximus had remained in memory
  6196.              the entire time.
  6197.  
  6198.              This feature is made possible by the "-r" command line pa-
  6199.              rameter. When Maximus is invoked using "-r", it reads a file
  6200.              called restar##.bbs from the \max directory. The Errorlevel
  6201.              exit routines will write this file to disk just before Maxi-
  6202.              mus executes the errorlevel command. The restar##.bbs file
  6203.              contains all of the information that Maximus needs to restart
  6204.              in its original state.
  6205.  
  6206.              When restarting Maximus with -r, you may also need to specify
  6207.              a number of other command line parameters. In particular:
  6208.  
  6209.              *  If you are using any of the following parameters:
  6210.  
  6211.  
  6212.  
  6213.              6. External Programs                                      108
  6214.  
  6215.                   -p, -s, -n, or an explicit .prm name
  6216.  
  6217.                 then you must also include these parameters in your call to
  6218.                 "max -r".
  6219.  
  6220.                 For example, if your standard Maximus start-up command
  6221.                 looks like this:
  6222.  
  6223.                 max system2 -w -p2 -n3
  6224.  
  6225.                 then the call to restart Maximus with the -r parameter must
  6226.                 look like this:
  6227.  
  6228.                 max system2 -p2 -n3 -r
  6229.  
  6230.  
  6231.        Warni Never attempt to use an errorlevel exit before a new caller
  6232.          ng! has reached the \max\misc\newuser2.bbs file. Maximus cannot
  6233.              perform a restart until it knows who the user is, and that
  6234.              means that the user must have entered a name, password,
  6235.              graphics selection, and so on.
  6236.  
  6237.              This sample batch file utilizes errorlevel batch files and
  6238.              the restart option:
  6239.  
  6240.                 rem * These first "%1 %2 %3" parameters will be
  6241.                 rem * passed to the batch file by your mailer.
  6242.                 rem * However, they are not really important
  6243.                 rem * when dealing with errorlevel batch files, so
  6244.                 rem * we will just assume that they are correct.
  6245.                 rem *
  6246.                 rem * Also, ensure that the ":DoErlvl" label
  6247.                 REM * comes after the main "Max -b%1 ..." command.
  6248.  
  6249.                 max -b%1 -p%2 -t%3 -n2
  6250.  
  6251.                 :DoErlvl
  6252.                 if errorlevel 65 goto Outside
  6253.                 REM * [..more errorlevels here..]
  6254.                 if errorlevel 1 goto end
  6255.                 goto end
  6256.  
  6257.                 :Outside
  6258.                 REM * Ensure that the number after the "-n" parameter
  6259.                 REM * specifies the Maximus task number to use, if
  6260.                 REM * not the one specified in the control file.
  6261.                 REM *
  6262.                 REM * Finally, if you are using a non-zero task
  6263.                 REM * number, keep in mind that the filename that
  6264.                 REM * Maximus writes will be "ERRORLxx.BAT", where
  6265.                 REM * "xx" is the task number in hexadecimal.
  6266.  
  6267.                 call C:\Max\Errorl02.Bat
  6268.  
  6269.  
  6270.  
  6271.              6. External Programs                                      109
  6272.  
  6273.                 Max -r -n2
  6274.                 goto DoErlvl
  6275.  
  6276.                 :End
  6277.  
  6278.              After you have created a batch file such as this, using er-
  6279.              rorlevel exits becomes just as easy as any of the other exit
  6280.              types. In MECCA, instead of using something of this format:
  6281.  
  6282.                   [xtern_run]D:\Path\Progname.Exe Arg1 Arg2
  6283.  
  6284.              one could easily use an Errorlevel exit as shown below:
  6285.  
  6286.                   [xtern_erlvl]65 D:\Path\Progname.Exe Arg1 Arg2
  6287.  
  6288.              As you can see, once you have added the errorlevel code to
  6289.              your batch files, adding new options requires only a minimal
  6290.              amount of work.
  6291.  
  6292.  
  6293.              6.5. External Program Translation Characters
  6294.  
  6295.              When specifying command line parameters for external pro-
  6296.              grams, and also in certain MECCA tokens, Maximus can include
  6297.              information about the current user by using special external
  6298.              program translation characters.
  6299.  
  6300.              A external program translation character consists of a per-
  6301.              cent sign and a single, case-sensitive letter or symbol.
  6302.              Maximus interprets the character following the percent sign
  6303.              and replaces it with the requested information.
  6304.  
  6305.              Table 6.2 describes the external program translation charac-
  6306.              ters supported by Maximus:
  6307.  
  6308.              Table 6.2 External Program Translation Characters
  6309.  
  6310.               Character   Translation
  6311.  
  6312.               %!          Embeds a newline in a string.
  6313.               %a          The number of calls that the user has made to
  6314.                           the system, prior to the current call.
  6315.               %A          The user's first name, in uppercase.
  6316.               %b          The user's baud rate. If the user is a local
  6317.                           caller, this translates to "0".
  6318.               %B          The user's last name in upper-case. If the
  6319.                           user has no last name, this token translates
  6320.                           into "NLN" ("No Last Name").
  6321.               %c          The user's city.
  6322.               %C          The response to the last [menu] MECCA token.
  6323.               %d          The current message area name.
  6324.               %D          The current file area name.
  6325.               %e          The user's password.
  6326.  
  6327.  
  6328.  
  6329.              6. External Programs                                      110
  6330.  
  6331.               %E          The user's screen length, in rows.
  6332.               %f          The user's first name, in mixed case.
  6333.               %F          Path to the current file area.
  6334.               %g          Graphics mode. (0 = TTY; 1 = ANSI; 2 = AVA-
  6335.                           TAR.)
  6336.               %G          Daily download limit (in kilobytes).
  6337.               %h          The user's phone number.
  6338.               %H          Number of kilobytes downloaded today
  6339.               %I          Total downloads (in kilobytes).
  6340.               %I          Total uploads (in kilobytes).
  6341.               %j          Minutes on-line for this call.
  6342.               %k          The current node number. ("0" means no node
  6343.                           number.)
  6344.               %K          The current node number in hexadecimal for-
  6345.                           mat, padded with leading zero to make it two
  6346.                           characters. ("00" for no task number.)
  6347.               %l          The user's last name in mixed case. If the
  6348.                           user has no last name, this token translates
  6349.                           into "NLN".
  6350.               %L          If the user is remote, this token translates
  6351.                           into the string "-pX -bY", where X is the
  6352.                           port number (1=COM1, 2=COM2, and so on) and Y
  6353.                           is the user's baud rate.
  6354.                           If the user is local, this translates into a
  6355.                           simple "-k".
  6356.               %m          The name of the first file to transfer when
  6357.                           invoking an external protocol.
  6358.               %M          Path to the current message area.
  6359.               %n          User's full name in mixed case.
  6360.               %N          The name of your BBS, as defined in the sys-
  6361.                           tem control file.
  6362.               %o          The user's privilege level.
  6363.               %p          The current port number (0=COM1, 1=COM2, and
  6364.                           so on).
  6365.               %P          The current port number (1=COM1, 2=COM2, and
  6366.                           so on).
  6367.               %q          Path to the current message area (with no
  6368.                           trailing backslash).
  6369.               %Q          Path to the current file area (with no trail-
  6370.                           ing backslash).
  6371.               %r          The user's real name, if applicable.
  6372.               %R          All remaining stacked text in the keyboard
  6373.                           buffer, as entered at the last menu.
  6374.               %s          The SysOp's last name in mixed case. If the
  6375.                           SysOp has no last name, this translates into
  6376.                           "NLN".
  6377.               %S          The SysOp's first name in mixed case.
  6378.               %t          The amount of time the user has left (in min-
  6379.                           utes).
  6380.               %T          The amount of time the user has left (in sec-
  6381.                           onds).
  6382.               %u          The user's lastread pointer number. This to-
  6383.                           ken translates into a unique integer for each
  6384.  
  6385.  
  6386.  
  6387.              6. External Programs                                      111
  6388.  
  6389.                           user on the system. This number is guaranteed
  6390.                           not to change, even if the user file is
  6391.                           sorted.
  6392.               %U          Translates to a simple underscore.
  6393.               %v          Upload path for the current file area (with
  6394.                           trailing backslash).
  6395.               %V          Upload path for the current file area (with
  6396.                           no trailing backslash).
  6397.               %w          The path to the current files.bbs-type file.
  6398.                           This takes into account the alternate names
  6399.                           which may be used by the FileList option.
  6400.               %W          The "steady baud rate," as passed via the -s
  6401.                           command line parameter.
  6402.               %x          Drive letter of current drive, in upper case.
  6403.               %X          The last-read message number for the current
  6404.                           message area.
  6405.               %Y          The user's current language number. (0 is the
  6406.                           first language in language.ctl; 1 is second,
  6407.                           and so on.)
  6408.               %Z          Translates to the user's full name, in caps.
  6409.  
  6410.  
  6411.  
  6412.              In addition to the above translation characters, Maximus also
  6413.              supports a similar set of translation characters for display
  6414.              filenames:
  6415.  
  6416.              In any Display_File command or .bbs filename, Maximus can use
  6417.              any of the above external program translation characters.
  6418.              However, the first character of the sequence must be a "+"
  6419.              rather than a "%".
  6420.  
  6421.              For example, to display a file called d:\#.bbs, where # is
  6422.              the current node number, you can include the following com-
  6423.              mand in the menu control file:
  6424.  
  6425.                 Display_File     D:\+k.bbs    Demoted   "Display it!"
  6426.  
  6427.              Remember, the "+" is only used when specifying a translation
  6428.              character for a display filename. The percent sign is used in
  6429.              all other cases.
  6430.  
  6431.              Lastly, one shortcut can also be used for menu names. If you
  6432.              wish to substitute the current node number in a menu file-
  6433.              name, insert the "*" character.
  6434.  
  6435.              For example, the following line:
  6436.  
  6437.                   First Menu MAIN*
  6438.  
  6439.              causes node 0 to display a menu called main00.mnu; node 1
  6440.              will display main01.mnu, and so on. (The task number is in
  6441.              hexadecimal, so node 12 would display main0c.mnu.)
  6442.  
  6443.  
  6444.  
  6445.              6. External Programs                                      112
  6446.  
  6447.              6.6. Running Doors
  6448.  
  6449.              A door is just a fancy name for external programs that can
  6450.              communicate with an on-line user. Door programs contain rou-
  6451.              tines to communicate with the modem, allowing the door to en-
  6452.              sure that the user does not drop carrier and to check the
  6453.              user's time limit.
  6454.  
  6455.              However, some doors presents special problems. Several con-
  6456.              flicting standards exist for door interfaces. The door inter-
  6457.              face describes how the calling BBS program (Maximus) inter-
  6458.              faces with the door program. For example, most doors need to
  6459.              know the user's name, whether or not the user supports ANSI
  6460.              graphics, and so on.
  6461.  
  6462.              Maximus includes the capability to directly write any text-
  6463.              based door interface file using a simple MECCA file. (In ad-
  6464.              dition, MEX can be used to write almost any binary-based door
  6465.              interface file.)
  6466.  
  6467.              The distribution version of Maximus comes with MECCA files
  6468.              which allow you to create door interface files for the fol-
  6469.              lowing formats:
  6470.  
  6471.              *  dorinfo1.def (QuickBBS and RBBS)
  6472.              *  chain.txt (WWIV)
  6473.              *  callinfo.bbs (WildCat!)
  6474.              *  door.sys (GAP and others)
  6475.  
  6476.              In addition, you can write your own MECCA or MEX programs to
  6477.              generate almost any other type of text or binary-based door
  6478.              interface file.
  6479.  
  6480.              This functionality is achieved through the [write] MECCA to-
  6481.              ken. The [open] and [post] tokens are also used when writing
  6482.              door interface files.
  6483.  
  6484.              The [write] token simply writes a line of text to a file
  6485.              opened with [open], but it also makes translations to the
  6486.              string using external program translation characters.
  6487.  
  6488.              For example, to instruct Maximus to write a QuickBBS or RBBS-
  6489.              compatible dorinfo1.def file, simply copy the following MECCA
  6490.              script into a file called dorinfo.mec and compile it. (The
  6491.              standard distribution version of Maximus includes this file
  6492.              in \max\misc\dorinfo.mec.)
  6493.  
  6494.                 [delete]Dorinfo1.Def
  6495.                 [open]Dorinfo1.Def
  6496.                 [write]%N[ comment           Write the BBS name           ]
  6497.                 [write]%S[ comment           Write the SysOp's first name ]
  6498.                 [write]%s[ comment           Write the SysOp's last name  ]
  6499.                 [islocal write]COM0[ comment          Write the COM port  ]
  6500.  
  6501.  
  6502.  
  6503.              6. External Programs                                      113
  6504.  
  6505.                 [isremote write]COM%P[comment       (local is always COM0)]
  6506.                 [write]%b BAUD,N,8,1[comment Write the baud rate          ]
  6507.                 [write] 0[ comment           Say that we're not networked ]
  6508.                 [write]%A[ comment           Write the user's first name  ]
  6509.                 [write]%B[ comment           Write the user's last name   ]
  6510.                 [write]%c[ comment           Write the user's city        ]
  6511.                 [write]%g[ comment           Write the user's graphics    ]
  6512.                 [write]%o[ comment           Write the user's security lvl]
  6513.                 [write]%t[ comment           Write the user's time remain ]
  6514.                 [write]-1[ comment           Say that we're using a FOSSIL]
  6515.                 [quit      comment           And we're done!              ]
  6516.  
  6517.              You can create similar files for other door interface types
  6518.              by simply creating another MECCA file with the appropriate
  6519.              commands.
  6520.  
  6521.              Before running an external program, Maximus can create the
  6522.              dorinfo1.def file (or any of the above-mentioned files) in
  6523.              one of three ways:
  6524.  
  6525.              Create dorinfo1.def from a .mec file. Simply include the fol-
  6526.              lowing line before the call to [xtern_dos] or [xtern_run]:
  6527.  
  6528.                 [link]C:\Max\Misc\Dorinfo
  6529.  
  6530.              As mentioned earlier, the distribution version of Maximus
  6531.              also comes with MECCA scripts to generate several other types
  6532.              of door interfaces. The format for using these interface
  6533.              files is similar:
  6534.  
  6535.                 [link]C:\Max\Misc\WWIV     - To create CHAIN.TXT
  6536.                 [link]C:\Max\Misc\CallInfo - To create CALLINFO.BBS
  6537.                 [link]C:\Max\Misc\DoorSys  - To create DOOR.SYS
  6538.  
  6539.              Create dorinfo1.def from a menu option. Similarly, you can
  6540.              achieve the same results through a menu option. Simply link
  6541.              the appropriate door interface .bbs file to the menu option
  6542.              containing the command to run. (For more information on link-
  6543.              ing menu commands, please see section 4.7.3.
  6544.  
  6545.              For example, to instruct Maximus to create a dorinfo1.def
  6546.              file for a program called "C:\Max\Prg.Exe", use this in the
  6547.              menu control file:
  6548.  
  6549.                       Display_File C:\Max\Misc\Dorinfo Normal "RunPrg"
  6550.                 NoDsp Xtern_Run    C:\Max\Prg.Exe      Normal "R"
  6551.  
  6552.              This concept can be applied to the other door interface types
  6553.              by substituting the name of the door script for
  6554.              "C:\Max\Misc\Dorinfo".
  6555.  
  6556.              Create dorinfo1.def automatically for all menu programs. If
  6557.              you wish to have Maximus write dorinfo1.def every time it ex-
  6558.  
  6559.  
  6560.  
  6561.              6. External Programs                                      114
  6562.  
  6563.              its for an external program from a menu option, simply edit
  6564.              the Uses Leaving statement in the system control file:
  6565.  
  6566.                 Uses Leaving C:\Max\Misc\Dorinfo
  6567.  
  6568.              This instructs Maximus to create dorinfo1.def whenever Maxi-
  6569.              mus runs an external program from a menu option.
  6570.  
  6571.  
  6572.              6.7. On-Line User Record Modification
  6573.  
  6574.              Some door programs are written specifically for Maximus, and
  6575.              these programs occasionally need to directly change part of a
  6576.              user's profile, such as the user's remaining time,
  6577.              ANSI/AVATAR preference, phone number, and so on. Some of
  6578.              these programs need to do this even while the user is on-
  6579.              line.
  6580.  
  6581.              Maximus supports on-line user record modification for most
  6582.              exit types. When instructed to do so, it will re-read the
  6583.              lastus##.bbs file for the current node after returning from
  6584.              an external program.
  6585.  
  6586.              If you are running the external program as a menu option,
  6587.              then the fastest way to enable on-line modification is to
  6588.              place the ReRead modifier in front of the usual Xtern_* op-
  6589.              tion. In other words, instead of invoking the program like
  6590.              this:
  6591.  
  6592.                        Xtern_Run D:\Path\Prog.Exe Demoted "Prog"
  6593.  
  6594.              you must place add a ReRead modifier as follows:
  6595.  
  6596.                 ReRead Xtern_Run D:\Path\Prog.Exe Demoted "Prog"
  6597.  
  6598.              Similarly, you can perform the same operation when using the
  6599.              [xtern_*] MECCA tokens by using an "@" as the first character
  6600.              of the program name. in other words, instead of invoking the
  6601.              program like this:
  6602.  
  6603.                 [xtern_run]D:\Path\Prog.Exe
  6604.  
  6605.              you must use this instead:
  6606.  
  6607.                 [xtern_run]@D:\Path\Prog.Exe
  6608.  
  6609.              However, keep in mind that most programs do not need this
  6610.              feature. For security reasons, you should not use this fea-
  6611.              ture unless the external program's documentation states that
  6612.              on-line modification is required.
  6613.  
  6614.  
  6615.  
  6616.              6. External Programs                                      115
  6617.  
  6618.              6.8. Doors and OS/2
  6619.  
  6620.              OS/2-based communications programs can only run other OS/2-
  6621.              based programs as doors. Normally, DOS-based doors cannot be
  6622.              run under the OS/2 version of Maximus.
  6623.  
  6624.              However, if you are using the third-party SIO.SYS communica-
  6625.              tion driver, some DOS doors can be made to work with the OS/2
  6626.              version of Maximus. See the documentation that comes with SIO
  6627.              for more information.
  6628.  
  6629.              Aside from this restrictions, running OS/2-specific doors is
  6630.              usually much easier than running DOS-based doors. OS/2 pro-
  6631.              grams do not have a 640k memory limitation, so there is no
  6632.              need for swapping or the Xtern_Erlvl feature.
  6633.  
  6634.              One feature of OS/2 communications programs is that they all
  6635.              use "port handles" when passing control from one program to
  6636.              another. A port handle is created by the DosOpen system call
  6637.              when an application opens a COM port. The port handle is dif-
  6638.              ferent from the port number; the handle is assigned automati-
  6639.              cally by the operating system, and it is not the same as the
  6640.              port number.
  6641.  
  6642.              To allow other applications to access the port, the program
  6643.              that "owns" the port spawns the door program directly, giving
  6644.              it the port handle number for the open communications port.
  6645.              The spawned program must use this handle to communicate with
  6646.              the port. (For example, when spawning Maximus from a front
  6647.              end mailer program, the "-p" command line parameter is used
  6648.              to pass a port handle number.)
  6649.  
  6650.              Due to OS/2's file handle sharing architecture, any attempt
  6651.              to access the port without using the handle number will fail.
  6652.              This is why DOS doors cannot normally be used under Maximus-
  6653.              OS/2; DOS programs do not know about port handles, so they
  6654.              cannot inherit the port from an OS/2 communications program.
  6655.              However, see the SIO.SYS documentation for information on how
  6656.              to get around this problem.
  6657.  
  6658.  
  6659.  
  6660.  
  6661.  
  6662.  
  6663.  
  6664.  
  6665.                                                     7. Multinode Operations
  6666.  
  6667.              Maximus supports an integrated paging and internode chat fa-
  6668.              cility, making Maximus the ideal choice for multinode sys-
  6669.              tems. Maximus is also LAN-friendly, meaning that it can run
  6670.              on any Netware, LANtastic, LAN Manager or LAN Server network,
  6671.              in addition to any other DOS-based network that supports file
  6672.              sharing.
  6673.  
  6674.              To run a multinode version of Maximus, you need at least one
  6675.              of the following:
  6676.  
  6677.              *  MS-DOS/PC-DOS with a multitasking environment (Windows or
  6678.                 DESQview),
  6679.  
  6680.              *  OS/2, Windows NT, Windows 95, or any other operating system
  6681.                 with built-in multitasking capabilities, or
  6682.  
  6683.              *  two or more computers running networking software.
  6684.  
  6685.              With the first two options, you can run multiple copies of
  6686.              Maximus on a single computer. With the latter option, you can
  6687.              run a single copy of Maximus on multiple networked computers.
  6688.              Combinations of the two approaches are also possible, such as
  6689.              networking two machines that each run four copies of Maximus.
  6690.  
  6691.              If you decide to run multiple copies of Maximus on a single
  6692.              computer, you should ensure that your hardware is fast enough
  6693.              to run all nodes at full speed. The exact hardware require-
  6694.              ments vary based on the system manufacturer, bus architec-
  6695.              ture, clock speed, available system memory, and the speed of
  6696.              the modems on your system.
  6697.  
  6698.              However, some general rules are:
  6699.  
  6700.              *  If you are running the DOS version of Maximus, unless you
  6701.                 have a very fast computer, it is unwise to run more than
  6702.                 four nodes per machine. DOS was not designed to handle mul-
  6703.                 titasking applications, and a lot of CPU time is wasted
  6704.                 performing unnecessary context switching and polling for
  6705.                 hardware events.
  6706.  
  6707.              *  If you are running the OS/2 version of Maximus, you can
  6708.                 easily run 16 nodes (or more) on a fast computer, as long
  6709.                 as you are using intelligent serial port hardware. The fol-
  6710.                 lowing intelligent serial boards are known to work with the
  6711.                 OS/2 version of Maximus:
  6712.  
  6713.                 * IBM's ARCTIC (RIC) card
  6714.                 * DigiBoard's "DigiBoard/i" series
  6715.  
  6716.  
  6717.  
  6718.              7. Multinode Operations                                   118
  6719.  
  6720.  
  6721.              *  Without an intelligent serial board, the OS/2 version of
  6722.                 Maximus can probably handle 8 nodes on one machine, depend-
  6723.                 ing on your system's clock speed and other hardware capa-
  6724.                 bilities.
  6725.  
  6726.              *  If you are not using an intelligent serial board, for ei-
  6727.                 ther the DOS or OS/2 version of Maximus, you will require a
  6728.                 16550 UART (serial interface chip) on all serial ports that
  6729.                 are serviced by Maximus.
  6730.  
  6731.                 Many high-speed internal modems come with 16550 chips built
  6732.                 in, but if you are using external modems, many older serial
  6733.                 port boards only have the inferior 8250 or 16450 chip. The
  6734.                 8250 and 16450 are usually socketed, so most computer deal-
  6735.                 ers will be able to replace them for you by simply swapping
  6736.                 in new chips.
  6737.  
  6738.                 The 16550 chip includes a number of buffering features that
  6739.                 prevent characters from being lost during periods of high
  6740.                 system load. The 16550 can also accept data much more
  6741.                 quickly than the 16450.
  6742.  
  6743.  
  6744.              7.1. Installation
  6745.  
  6746.              Installation of a multinode version of Maximus is identical
  6747.              to the installation procedure for a single-node version of
  6748.              Maximus. However, you may want to keep these points in mind:
  6749.  
  6750.              *  If you are installing Maximus on a network, you should in-
  6751.                 stall it on a drive that can be accessed using the same
  6752.                 drive letter on all workstations and servers that will be
  6753.                 running copies of Maximus. If you are running Maximus on a
  6754.                 non-dedicated server, you should probably run the Maximus
  6755.                 session through the redirected version of the drive.
  6756.  
  6757.                 For example, assume that you have installed Maximus on
  6758.                 \\MYSERVER on the d:\max directory. In addition, assume
  6759.                 that all workstations access the Maximus drive with a "net
  6760.                 use w: \\myserver\max" command.
  6761.  
  6762.                 Given this configuration, you should set up all of the
  6763.                 Maximus control files to look for Maximus on the W: drive.
  6764.                 (In fact, it is better to install Maximus directly to the
  6765.                 W: drive and let the install program configure these set-
  6766.                 tings for you.)
  6767.  
  6768.                 If you wish to run Maximus on the server machine, you
  6769.                 should still execute a "net use w: \\myserver\max" and run
  6770.                 the system from the W: drive, even though the information
  6771.                 is stored locally in d:\max. (Otherwise, you would need two
  6772.  
  6773.  
  6774.  
  6775.              7. Multinode Operations                                   119
  6776.  
  6777.                 separate sets of control files ---one that pointed to
  6778.                 d:\max and one that pointed to the W: drive.)
  6779.  
  6780.              *  Maximus-OS/2 supports UNC paths, so you can directly spec-
  6781.                 ify directories and filenames such as
  6782.                 \\myserver\max\max\misc\welcome.bbs. However, many other
  6783.                 programs do not accept UNC paths, so you should use this
  6784.                 option with caution.
  6785.  
  6786.              *  You will normally need a separate batch or command file for
  6787.                 each copy of Maximus that you wish to run. However, you
  6788.                 only need one copy of the Maximus executables and system
  6789.                 files.
  6790.  
  6791.                 When writing batch files to start Maximus, the command line
  6792.                 switches shown below in Table 7.1 allow you to tailor Maxi-
  6793.                 mus to run as a different node number.
  6794.  
  6795.                 Table 7.1 Multinode Command Line Switches
  6796.  
  6797.                 Parameter    Description
  6798.  
  6799.                 -p<num>      Specify an alternate COM port.
  6800.                 -b<speed>    Specify an alternate maximum baud rate.
  6801.                 -n<node>     Specify an alternate node number.
  6802.                 -l<file>     Specify an alternate log filename.
  6803.  
  6804.  
  6805.                 The -n and -l parameters allow you to adjust the task num-
  6806.                 ber and log filenames at runtime. All nodes need a distinct
  6807.                 node number, and all nodes need a separate log file.
  6808.  
  6809.                 In addition, if you are running multiple nodes of Maximus
  6810.                 on the same machine, you will probably also need to config-
  6811.                 ure each node to use a separate COM port number and speed,
  6812.                 using the -p and -b parameters.
  6813.  
  6814.                 Please see Appendix C for more information on these command
  6815.                 line parameters.
  6816.  
  6817.              *  Using DOS or OS/2 environment variables, you can actually
  6818.                 run multiple copies of Maximus with only one batch file. If
  6819.                 you set an environment variable to the current node number,
  6820.                 like this:
  6821.  
  6822.                 set THISNODE=2
  6823.  
  6824.                 you can then refer to that variable within a batch file as
  6825.                 "%THISNODE%". Similarly, you can also set up variables for
  6826.                 the port number, baud rate, log file, and so on.
  6827.  
  6828.                 You can then create a runbbs.bat or runbbs.cmd that con-
  6829.                 tains a command like this:
  6830.  
  6831.  
  6832.  
  6833.              7. Multinode Operations                                   120
  6834.  
  6835.                 max -p%thisport% -n%thisnode% -l%thislog%
  6836.  
  6837.                 As long as the environment variables are set up correctly
  6838.                 before executing your runbbs.bat, you only need to maintain
  6839.                 one copy of the file.
  6840.  
  6841.              *  If you wish to display node-specific information to users,
  6842.                 you can use the "*" token in the names of .bbs display
  6843.                 files and system menus. The "*" will be replaced with a
  6844.                 two-digit hexadecimal task number. This allows you to add a
  6845.                 command such as this:
  6846.  
  6847.                 Display_File   Misc\Bullet*    Demoted "Bulletins"
  6848.  
  6849.                 On node 1, selecting this option would display
  6850.                 \max\misc\bullet01.bbs.
  6851.  
  6852.              *  All copies of Maximus must be started from the same direc-
  6853.                 tory. This allows you to share some files between nodes, in
  6854.                 addition to providing a clean directory structure.
  6855.  
  6856.              *  If you are part of a FidoNet technology network, you may
  6857.                 only want to run a front end mailer on one line. The inter-
  6858.                 nal WFC subsystem can be enabled on a node-by-node basis:
  6859.                 simply include a -w on the command line for those nodes
  6860.                 that are to run in WFC mode.
  6861.  
  6862.              *  In your system startup file (either autoexec.bat for DOS or
  6863.                 startup.cmd for OS/2), you should include commands to de-
  6864.                 lete the following files from the Maximus directory struc-
  6865.                 ture:
  6866.  
  6867.                   \max\active*.bbs
  6868.                   \max\qwk_busy.$$$
  6869.                   \max\ipc\*.bbs
  6870.  
  6871.                 These temporary files are created during normal Maximus op-
  6872.                 eration. However, if a Maximus session ends abnormally,
  6873.                 some of the files above may be left around. These files
  6874.                 should be deleted to prevent confusion when Maximus starts
  6875.                 up again.
  6876.  
  6877.                 In the case of a network installation, the commands to de-
  6878.                 lete the above files should be placed in the startup file
  6879.                 on the server, not on the workstations.
  6880.  
  6881.              *  If you wish to use the multinode chat or the paging fea-
  6882.                 tures, your operating system must support file and record
  6883.                 locking. Under DOS, this means that you must load the
  6884.                 share.exe program, as described in the installation in-
  6885.                 structions. (Under OS/2 and Windows 95, file locking is
  6886.                 built into the operating system, so no special utilities
  6887.                 are necessary.)
  6888.  
  6889.  
  6890.  
  6891.              7. Multinode Operations                                   121
  6892.  
  6893.              *  Ensure that all copies of Maximus have a unique and non-
  6894.                 zero node number. If the task number is set to zero, Maxi-
  6895.                 mus will assume that your system is running in a single-
  6896.                 node environment, so that node will not be able to communi-
  6897.                 cate with the rest of the system.
  6898.  
  6899.                 However, if you wish to create a "hidden" node for local
  6900.                 logons, you may want to configure that node to run as node
  6901.                 0. This node will be invisible to the rest of the system,
  6902.                 but it will otherwise function normally.
  6903.  
  6904.              *  For information on installing Maximus on a networked OS/2
  6905.                 system, please see the Master Control Program guide in sec-
  6906.                 tion 7.3.
  6907.  
  6908.  
  6909.              7.2. Multinode Chat Operation
  6910.  
  6911.              Maximus includes a built-in multinode chat and paging facil-
  6912.              ity. Users can be paged by others, participate in real-time
  6913.              conferences (both public and private), display a list of on-
  6914.              line users, and more.
  6915.  
  6916.          DOS For DOS users, the first step in configuring the multinode
  6917.        only! chat is to enable the Path IPC statement in the system con-
  6918.              trol file. For optimal performance, this directory should be
  6919.              placed on a RAM disk, but it can also be placed in a normal
  6920.              directory.
  6921.  
  6922.              For either OS/2 or DOS users, the next step is to edit the
  6923.              menus control file and ensure that the Display_Menu CHAT op-
  6924.              tion is uncommented.
  6925.  
  6926.              Having made these changes, recompile the control files and
  6927.              log on locally to test the system. (You will need to use two
  6928.              different user names, since Maximus only allows a user to log
  6929.              onto one node at a time.)
  6930.  
  6931.              Before testing chat mode, enter the Chat Section and look at
  6932.              the menu display. The table should show the list of on-line
  6933.              callers. If the display is blank, something is not configured
  6934.              correctly:
  6935.  
  6936.              *  Under DOS, ensure that you have loaded share.exe, as indi-
  6937.                 cated in the installation instructions.
  6938.  
  6939.              *  Under DOS, ensure that the Path IPC for all nodes points to
  6940.                 the same directory.
  6941.  
  6942.              *  Under OS/2, ensure that the mcp.exe program is in the main
  6943.                 \max directory or somewhere else on your PATH statement.
  6944.  
  6945.  
  6946.  
  6947.              7. Multinode Operations                                   122
  6948.  
  6949.              If the menu display seems to be in order, try toggling your
  6950.              "chat availability" flag a few times. After your status has
  6951.              been toggled, the "Status" portion of the table should indi-
  6952.              cate whether or not you are available for chat. Then switch
  6953.              to the other node and redisplay the chat menu. You should see
  6954.              that the status of the first node is also reflected on the
  6955.              screen of the second node.
  6956.  
  6957.              Finally, after confirming that everything else is working
  6958.              properly, you can enter multinode chat. To initiate a chat,
  6959.              select the Page option and enter the number of the node to be
  6960.              paged. Under DOS, it may take up to 15 seconds for the chat
  6961.              request to register on the other node, but under OS/2, the
  6962.              other user should be notified instantly.
  6963.  
  6964.              On the other user's console, you should see a "You are being
  6965.              paged by John Doe (node ##)" message. This is the standard
  6966.              paging message; to modify it, you can either edit the eng-
  6967.              lish.mad language file, or you can create a separate display
  6968.              file as \max\misc\chatpage.bbs.
  6969.  
  6970.              To answer the chat request on the other node, select the An-
  6971.              swer Page option and enter the node number of the user who
  6972.              sent the request. This will place the user in chat mode as
  6973.              well. The first user should see a "Jane Doe joins the conver-
  6974.              sation" message, which indicates that the other user answered
  6975.              the chat request.
  6976.  
  6977.              The user who answered the page will not see anything immedi-
  6978.              ately; to find out who is participating in the conversation,
  6979.              simply type a "/w" command at the beginning of a line. To
  6980.              list all of the callers on the system, whether or not they
  6981.              are in chat mode, type "/s".
  6982.  
  6983.              Once in chat, users can send messages to each other by simply
  6984.              typing the text that they wish to send. Maximus will auto-
  6985.              matically word-wrap at the end of lines, and the text will be
  6986.              transmitted one line at a time. Try typing a few lines from
  6987.              each node to ensure that the chat function is working prop-
  6988.              erly.
  6989.  
  6990.              Once you are finished testing, you can use the "/q" command
  6991.              on each node to exit chat mode. (When a node exits chat, the
  6992.              other nodes participating in the same chat should see a "John
  6993.              Doe leaves the conversation" message.)
  6994.  
  6995.              In addition to the private chat facility, Maximus also sup-
  6996.              ports a group chat, or a "virtual CB channel." The CB chat is
  6997.              useful when you have three or more nodes and want to have
  6998.              more than two callers participating in a conversation. Maxi-
  6999.              mus supports up to 255 concurrent "channels," which means
  7000.              that there can be up to 255 separate conversations going on
  7001.              at the same time.
  7002.  
  7003.  
  7004.  
  7005.              7. Multinode Operations                                   123
  7006.  
  7007.              However, the CB chat has no paging ability; it is up to the
  7008.              callers to look at the status screen in the Chat Section and
  7009.              find out which channel is being used by the other users.
  7010.  
  7011.              For more information on using Maximus's multinode chat,
  7012.              please see the chat help file. (To display the help file, en-
  7013.              ter "/?" from inside chat mode.)
  7014.  
  7015.  
  7016.              7.3. Master Control Program
  7017.  
  7018.         OS/2 The OS/2 version of Maximus uses the Master Control Program
  7019.        only! server (MCP) for all multinode communication. When Maximus
  7020.              loads, it automatically starts the MCP server and runs it as
  7021.              a background task. The server then creates a number of named
  7022.              pipes that are used for communication among Maximus nodes.
  7023.  
  7024.              On a non-networked machine, this is ideal, since all Maximus
  7025.              tasks reside on the same machine, and they all communicate
  7026.              with the local MCP server by default.
  7027.  
  7028.              However, if you are running copies of Maximus on multiple
  7029.              workstations, they will try to talk to the MCP running on the
  7030.              workstation, not on the server. To prevent this, you must
  7031.              start a copy of MCP on the server yourself, and you must tell
  7032.              each node where to find the MCP server.
  7033.  
  7034.              Starting the MCP server. The MCP server should be started
  7035.              from the config.sys file on the network server, as shown be-
  7036.              low:
  7037.  
  7038.                 RUN=c:\max\mcp.exe . \pipe\maximus\mcp <nodes> server
  7039.  
  7040.              The nodes parameter tells MCP to support up to nodes concur-
  7041.              rent tasks. This parameter should have the same value as the
  7042.              MCP Sessions definition in the system control file. The nodes
  7043.              parameter should be greater than the maximum number of Maxi-
  7044.              mus nodes that you expect to run at one time. (It is an error
  7045.              to specify too few nodes, but you can specify more nodes
  7046.              without worry.)
  7047.  
  7048.              Configuring the workstations to use the MCP server. In the
  7049.              main system control file, the MCP Pipe definition can be used
  7050.              to configure the location of the MCP server. The default pipe
  7051.              is \pipe\maximus\mcp, but you must change this to point to
  7052.              the server.
  7053.  
  7054.              If MCP is running on the server called \\myserver, you must
  7055.              edit the MCP Pipe definition to read:
  7056.  
  7057.                 MCP Pipe    \\myserver\pipe\maximus\mcp
  7058.  
  7059.  
  7060.  
  7061.              7. Multinode Operations                                   124
  7062.  
  7063.              In addition, you can also use the -a command line parameter
  7064.              to override the MCP Pipe setting in the system control file.
  7065.  
  7066.  
  7067.  
  7068.  
  7069.  
  7070.  
  7071.  
  7072.  
  7073.                                                    8. Utility Documentation
  7074.  
  7075.              This section describes the command line interface of the
  7076.              various utility programs that are included in the Maximus
  7077.              distribution.
  7078.  
  7079.  
  7080.              8.1. ACCEM: MECCA Decompiler
  7081.  
  7082.  
  7083.              8.1.1. Description
  7084.  
  7085.              ACCEM is the inverse of the MECCA utility: ACCEM reads a com-
  7086.              piled .bbs file and converts it into a human-readable .mec
  7087.              file. This functionality can be useful if you have lost the
  7088.              source for one of your .bbs display files, or if you are try-
  7089.              ing to change a compiled .bbs file which was given to you by
  7090.              someone else.
  7091.  
  7092.              After running ACCEM on a .bbs file, you can freely edit the
  7093.              resulting .mec file and recompile it as you wish. The .mec
  7094.              file created with ACCEM should be identical to the original
  7095.              .mec file, with one small exception: label names are not
  7096.              stored in the .bbs file, so ACCEM will create numbered la-
  7097.              bels. For example, the following MECCA sequence:
  7098.  
  7099.                 [goto foo]
  7100.  
  7101.                 [/foo]
  7102.  
  7103.              could be decompiled into the following:
  7104.  
  7105.                 [goto L1]
  7106.  
  7107.                 [/L1]
  7108.  
  7109.              Although the labels are different, the .mec file will still
  7110.              compile correctly.
  7111.  
  7112.  
  7113.              8.1.2. Command Line Format
  7114.  
  7115.              The command line format for ACCEM is:
  7116.  
  7117.                 accem infile [outfile] [-s]
  7118.  
  7119.              infile is the name of the .bbs file to convert. If no exten-
  7120.              sion is given, ACCEM assumes an extension of .bbs.
  7121.  
  7122.  
  7123.  
  7124.              8. Utility Documentation                                  126
  7125.  
  7126.              outfile is the optional name of the .mec output file. If this
  7127.              parameter is omitted, ACCEM will assume the name specified
  7128.              for infile, but using a .mec extension.
  7129.  
  7130.              The -s switch instructs ACCEM to split lines which are longer
  7131.              than 100 characters. When ACCEM needs to split a line, it
  7132.              will place an opening brace in the 100th column of the line,
  7133.              and it will place the closing brace at the beginning of the
  7134.              next line. This option is useful if your text editor can only
  7135.              display a limited number of columns.
  7136.  
  7137.              For example, to convert test.bbs to test.mec, any of the fol-
  7138.              lowing commands will work:
  7139.  
  7140.                 accem test
  7141.                 accem test.bbs
  7142.                 accem test.bbs test.mec
  7143.  
  7144.              To split lines which are over 100 characters in length, the
  7145.              following commands would also work:
  7146.  
  7147.                 accem test -s
  7148.                 accem test.bbs -s
  7149.                 accem test.bbs test.mec -s
  7150.  
  7151.  
  7152.              8.2. ANS2BBS/MEC: ANSI to MEC conversion
  7153.  
  7154.  
  7155.              8.2.1. Description
  7156.  
  7157.              ANS2BBS and ANS2MEC convert ANSI graphics into MECCA tokens.
  7158.              ANS2BBS and ANS2MEC can convert almost any file containing
  7159.              ANSI graphics into an equivalent MECCA display file that can
  7160.              be processed by Maximus.
  7161.  
  7162.              ANS2BBS will convert a file containing ANSI graphics directly
  7163.              into a .bbs file that can be displayed by Maximus. ANS2MEC
  7164.              converts an ANSI file into a MECCA source file. The created
  7165.              .mec file can then be edited and compiled as usual.
  7166.  
  7167.              ANS2BBS is useful for a one-time translation, but ANS2MEC is
  7168.              best if you wish to add some special effects to the display
  7169.              file or clean up some of the display codes.
  7170.  
  7171.  
  7172.              8.2.2. Command Line Format
  7173.  
  7174.              The format for ANS2BBS (and ANS2MEC) is as follows:
  7175.  
  7176.                 ans2bbs infile [outfile]
  7177.                 ans2mec infile [outfile]
  7178.  
  7179.  
  7180.  
  7181.              8. Utility Documentation                                  127
  7182.  
  7183.              infile is the name of the input ANSI graphics file. If no ex-
  7184.              tension is provided, an .ans extension is assumed by default.
  7185.  
  7186.              outfile is the optional name of the output file. For ANS2BBS,
  7187.              the default output file has a .bbs extension, whereas for
  7188.              ANS2MEC, the default output file has a .mec extension.
  7189.  
  7190.              ANS2BBS and ANS2MEC will try do the best job that they can
  7191.              when converting an ANSI file, but due to some ambiguities in
  7192.              the ANSI cursor-movement syntax, they cannot always correctly
  7193.              convert all ANSI graphics files. ANS2BBS and ANS2MEC have
  7194.              problems with some "highly-animated" screens, particularly
  7195.              those generated by the "Diagonal," "Gate," "Squiggle," and
  7196.              other fancy drawing modes of the TheDraw program by Ian
  7197.              Davis. However, ANS2BBS and ANS2MEC can handle almost all
  7198.              straight-through ANSI files, so unless you are using one of
  7199.              those scanning modes, you should not have any problems.
  7200.  
  7201.              Once you have converted an ANSI screen, it is best to put it
  7202.              in a place where you can test it in local mode (or display it
  7203.              using the ORACLE utility). If the file did not convert cor-
  7204.              rectly and has formatting glitches, you have three choices:
  7205.  
  7206.              *  If the file is animated, load the file using TheDraw, turn
  7207.                 off animation mode by pressing Alt-J and then N. Save the
  7208.                 file and try ANS2BBS/ANS2MEC again.
  7209.  
  7210.              *  Convert the file using ANS2MEC, and edit the resulting
  7211.                 MECCA file to correct the problem.
  7212.  
  7213.              *  Leave the ANSI file as-is and display the ANSI version of
  7214.                 the file directly to callers. Although the ANSI codes will
  7215.                 not display properly on the local screen, they should be
  7216.                 displayed normally for remote callers.
  7217.  
  7218.  
  7219.              8.3. CVTUSR: User File Conversions
  7220.  
  7221.  
  7222.              8.3.1. Description
  7223.  
  7224.              CVTUSR converts foreign user files into the Maximus 3.0 user
  7225.              file format. CVTUSR can handle user files in the Maximus 1.0,
  7226.              Maximus 2.0, QuickBBS, RA 2.00, and Opus 1.0x formats.
  7227.  
  7228.  
  7229.              8.3.2. Command Line Format
  7230.  
  7231.              The command line format for CVTUSR is:
  7232.  
  7233.                 CVTUSR params
  7234.  
  7235.  
  7236.  
  7237.              8. Utility Documentation                                  128
  7238.  
  7239.              The params parameter can be one of the command line parame-
  7240.              ters shown in Table 8.1 below:
  7241.  
  7242.              Table 8.1 CVTUSR Command Line Switches
  7243.  
  7244.               Switch Description
  7245.  
  7246.               -l     Reset the lastread pointers in a Maximus 3.0 user
  7247.                      file. This option is normally only used to fix
  7248.                      cross-linked lastread pointers. Using this function
  7249.                      when it was not explicitly requested (by a note in
  7250.                      the Maximus log file) may destroy the lastread
  7251.                      pointers for existing users.
  7252.  
  7253.               -n     Convert an old Maximus version 1.x user file to the
  7254.                      Maximus 3.0 format.
  7255.  
  7256.               -o     Convert an Opus 1.10-style user.dat file to Maximus
  7257.                      3.0 format.
  7258.  
  7259.                      This procedure converts almost all of the Opus 1.10
  7260.                      user file fields, with the exception of the expiry
  7261.                      dates, personal welcome screens, and any utility-
  7262.                      specific fields which may be stored in the user
  7263.                      file.
  7264.  
  7265.               -p     Convert a Maximus version 2.x user file to the
  7266.                      Maximus 3.0 format.
  7267.  
  7268.               -q     This switch tells CVTUSR to convert a QuickBBS or
  7269.                      RA 2.00 users.bbs to a Maximus 3.0 user file. This
  7270.                      conversion is not as complete as some of the oth-
  7271.                      ers; for example, it will not convert the ANSI
  7272.                      graphics and "More" prompt settings.
  7273.  
  7274.                      WARNING! If your version of RA encrypts the pass-
  7275.                      words in the RA user file, CVTUSR will not be able
  7276.                      to convert the user file.
  7277.  
  7278.               -s     This flag tells CVTUSR to swap the "alias" and
  7279.                      "name" fields in the current Maximus 3.0 user file.
  7280.  
  7281.  
  7282.  
  7283.  
  7284.  
  7285.              8.4. EDITCAL: Call Modification Utility
  7286.  
  7287.  
  7288.              8.4.1. Description
  7289.  
  7290.              EDITCAL modifies the "number of callers to system" count in
  7291.              the bbstat##.bbs files. This program is useful if you have
  7292.  
  7293.  
  7294.  
  7295.              8. Utility Documentation                                  129
  7296.  
  7297.              recently changed from another BBS package, but you want to
  7298.              set the caller count to reflect the actual number of callers
  7299.              to your system.
  7300.  
  7301.  
  7302.              8.4.2. Command Line Format
  7303.  
  7304.              The command line format for EDITCAL is:
  7305.  
  7306.                 editcal node [num_calls]
  7307.  
  7308.              node is the node number whose "number of callers" count is to
  7309.              be modified.
  7310.  
  7311.              num_calls is the new "number of callers" value for the speci-
  7312.              fied node. If this parameter is omitted, EDITCAL will display
  7313.              the current "number of callers" count for the node.
  7314.  
  7315.  
  7316.              8.5. FB: File Database Compiler
  7317.  
  7318.  
  7319.              8.5.1. Description
  7320.  
  7321.              FB is the Maximus File Database compiler. FB compiles the AS-
  7322.              CII listings in the files.bbs directory listings into a for-
  7323.              mat which can be used by the global downloading routines, the
  7324.              upload duplicate file checker, and the Fast Locate feature.
  7325.              Maximus can use files.bbs directly in most situations, but
  7326.              many file area functions will run much faster if you use FB.
  7327.  
  7328.              By default, FB will extract information about file sizes and
  7329.              dates from the directory entries in the area's download di-
  7330.              rectory. However, if you have enabled Type DateList in a file
  7331.              area definition, FB can also extract file size and date in-
  7332.              formation from the ASCII file listing.
  7333.  
  7334.         OS/2 When you have file areas stored on an HPFS drive, FB will
  7335.        only! automatically use the HPFS "creation date" as the file upload
  7336.              date, and it will use the HPFS "last write date" as the
  7337.              file's true date. When requested to perform a new files
  7338.              search, Maximus will compare the requested date with the
  7339.              file's upload date. However, when displaying the file cata-
  7340.              log, Maximus will show the file's true date.
  7341.  
  7342.  
  7343.              8.5.2. Command Line Format
  7344.  
  7345.              The command line format for FB is:
  7346.  
  7347.                 fb switches [area ...]
  7348.  
  7349.  
  7350.  
  7351.              8. Utility Documentation                                  130
  7352.  
  7353.              The switches parameter must be one or more of the switches in
  7354.              Table 8.2 below:
  7355.  
  7356.              Table 8.2 FB Command Line Switches
  7357.  
  7358.               Switch    Description
  7359.  
  7360.               -a        Compile all file areas.
  7361.  
  7362.               -f<file>  Use <file> instead of the default farea.dat file
  7363.                         area database.
  7364.  
  7365.               -p<file>  Use <file> as the Maximus .prm file. This switch
  7366.                         overrides the MAXIMUS environment variable. FB
  7367.                         uses the .prm file to obtain information about
  7368.                         the main Maximus system directory, the name of
  7369.                         the file area database, and other file area set-
  7370.                         tings.
  7371.  
  7372.               -r        This switch forces FB to read information di-
  7373.                         rectly from the file directory, rather than read-
  7374.                         ing from the file area list. This switch only af-
  7375.                         fects areas declared using the Type FileList key-
  7376.                         word.
  7377.  
  7378.               -s        Skip areas marked as "Type Slow" or "Type CD."
  7379.  
  7380.               -u        Instead of processing the download paths for the
  7381.                         requested file areas, process the upload paths
  7382.                         instead. This parameter is used internally by the
  7383.                         runfb.bat and runfb.cmd files. (See below for
  7384.                         more information.)
  7385.  
  7386.               -x        Do not perform the final merge to maxfiles.idx.
  7387.  
  7388.  
  7389.  
  7390.              [area ...] is the optional list of areas to process. If a
  7391.              list of file areas is provided, FB will only include the
  7392.              listed areas in the file database. The wildcard "*" may be
  7393.              used at the end of a name to match any number of characters.
  7394.              (To build all file areas, use the "-a" switch instead.)
  7395.  
  7396.              Examples:
  7397.  
  7398.                 fb -a
  7399.  
  7400.              This command builds the file database for all file areas.
  7401.  
  7402.                 fb -s -a
  7403.  
  7404.              This command builds the file database for all file areas, ex-
  7405.              cept those on CD-ROM.
  7406.  
  7407.  
  7408.  
  7409.              8. Utility Documentation                                  131
  7410.  
  7411.                 fb 1 2 3 4
  7412.  
  7413.              Process only the files in areas 1, 2, 3 and 4.
  7414.  
  7415.                 fb os2.* dos.*
  7416.  
  7417.              Process all file areas that start with "os2." or "dos."
  7418.  
  7419.  
  7420.              8.5.3. Database Files
  7421.  
  7422.              When compiling a file area, FB will parse files.bbs, and for
  7423.              each file area, it will create the files shown in Table 8.3:
  7424.  
  7425.              Table 8.3 FB Database Files
  7426.  
  7427.               Filename   Description
  7428.  
  7429.               files.dat  A compiled version of each file's name, size,
  7430.                          timestamp, privilege level and flags.
  7431.               files.dmp  A compiled version of each file's description.
  7432.               files.idx  A sorted binary index of all files in the cur-
  7433.                          rent area.
  7434.  
  7435.  
  7436.  
  7437.              If you are using the FileList keyword in the file area defi-
  7438.              nition, Maximus will remove the extension of the FileList
  7439.              file and add .dat, .dmp and .idx as appropriate. For example,
  7440.              if you specified the following in a file area definition:
  7441.  
  7442.                 FileList  D:\Area1.Lst
  7443.  
  7444.              FB would create files called d:\area1.dat, d:\area1.dmp and
  7445.              d:\area1.idx. This allows owners of CD-ROMs to store all of
  7446.              the file area information in an alternate location.
  7447.  
  7448.  
  7449.              8.5.4. Database Building for Uploads
  7450.  
  7451.              Normally, after a user has uploaded a batch of files, the
  7452.              file database needs to be updated with the name and location
  7453.              of the uploaded files. Once the user has entered all of the
  7454.              file descriptions, Maximus tries to find a file called
  7455.              \max\runfb.bat or \max\runfb.cmd. If found, Maximus will exe-
  7456.              cute it with the following parameters:
  7457.  
  7458.                 runfb farea_dat areanum -u
  7459.  
  7460.              The farea_dat parameter is the name of the file area data
  7461.              file.
  7462.  
  7463.              The areanum parameter is the name of the current file area.
  7464.  
  7465.  
  7466.  
  7467.              8. Utility Documentation                                  132
  7468.  
  7469.              The -u parameter indicates that FB should build the database
  7470.              based on the upload paths.
  7471.  
  7472.              The standard runfb.bat file simply calls FB with the same pa-
  7473.              rameters as passed to it. Unfortunately, the database build
  7474.              process can take a long time for systems that have many
  7475.              files.
  7476.  
  7477.              In the default distribution, runfb.bat looks like this:
  7478.  
  7479.                 fb %1 %2 %3
  7480.  
  7481.              However, this line can be modified so that the file database
  7482.              is updated after the user logs off:
  7483.  
  7484.          DOS    echo fb %1 %2 %3 >>do_fb.bat
  7485.        only!
  7486.  
  7487.         OS/2    echo fbp %1 %2 %3 >>do_fb.cmd
  7488.        only!
  7489.  
  7490.              The above command creates a log of file areas to be updated.
  7491.              Your runbbs.bat should execute the following command after
  7492.              processing each caller:
  7493.  
  7494.          DOS    if exist do_fb.bat call do_fb.bat
  7495.        only!    if exist do_fb.bat del do_fb.bat
  7496.  
  7497.  
  7498.         OS/2    if exist do_fb.cmd call do_fb.cmd
  7499.        only!    if exist do_fb.cmd del do_fb.cmd
  7500.  
  7501.              These lines cause Maximus to perform all file database updat-
  7502.              ing after the caller logs off, which saves on both memory and
  7503.              on-line time. Ensure that the above commands are run after
  7504.              every caller, regardless of whether or not the caller entered
  7505.              NetMail, EchoMail, or no mail.
  7506.  
  7507.  
  7508.              8.6. MAID: Language File Compiler
  7509.  
  7510.  
  7511.              8.6.1. Description
  7512.  
  7513.              MAID is the Maximus Language File compiler. MAID takes a lan-
  7514.              guage definition, such as english.mad, and turns it into a
  7515.              form usable by Maximus. The language file can be used to sup-
  7516.              port non-English languages, or it can be used to simply
  7517.              change the prompts in the English version of Maximus.
  7518.  
  7519.  
  7520.  
  7521.              8. Utility Documentation                                  133
  7522.  
  7523.              8.6.2. Command Line Format
  7524.  
  7525.              The command line format for MAID is given below:
  7526.  
  7527.                 MAID langname [switches]
  7528.  
  7529.              The langname parameter is the full path and name of the lan-
  7530.              guage file. Do not include the .mad extension.
  7531.  
  7532.              The optional switches parameter can be zero or more of the
  7533.              switches shown in Table 8.4 below:
  7534.  
  7535.              Table 8.4 MAID Command Line Switches
  7536.  
  7537.               Switch     Description
  7538.  
  7539.               -d         Generate the dynamic language include file. The
  7540.                          langname.h file is not created unless you use
  7541.                          this switch.
  7542.               -n<name>   Use the name <name> as the name of the lan-
  7543.                          guage. This is the name that is displayed on
  7544.                          the Chg_Language menu when the user is asked to
  7545.                          select a language.
  7546.                          By default, MAID uses the base filename of the
  7547.                          language file as the language name. However,
  7548.                          the -n parameter can be used to specify an ex-
  7549.                          plicit language name. To include spaces in the
  7550.                          language name, enclose the entire parameter in
  7551.                          quotes like this:
  7552.  
  7553.                          maid english "-nAmericanEnglish"
  7554.  
  7555.               -p<prm>    After compiling a language file, MAID will
  7556.                          automatically update the Maximus parameter file
  7557.                          specified by the MAXIMUS environment variable.
  7558.                          However, if you want MAID to update a different
  7559.                          .prm file, the -p switch can be used to over-
  7560.                          ride the MAXIMUS environment variable.
  7561.                          Without this switch, and without a correctly-
  7562.                          set MAXIMUS environment variable, the system
  7563.                          control file must be recompiled every time you
  7564.                          change the language file.
  7565.               -s         Generate the static language include file. The
  7566.                          langname.lth file is not created unless you use
  7567.                          this switch.
  7568.  
  7569.  
  7570.  
  7571.              8.6.3. Language-Related Files
  7572.  
  7573.              MAID reads language source information from a file called
  7574.              langname.mad. The distribution version of Maximus comes with
  7575.              one language file called english.mad.
  7576.  
  7577.  
  7578.  
  7579.              8. Utility Documentation                                  134
  7580.  
  7581.              The different input and output files used by MAID are de-
  7582.              scribed in Table 8.5:
  7583.  
  7584.              Table 8.5 MAID Input and Output Files
  7585.  
  7586.               Extension    Description
  7587.  
  7588.               .mad         The Maximus International Definitions file.
  7589.                            This file contains the "source" for the lan-
  7590.                            guage and is the input to MAID. This file can
  7591.                            be edited with an ordinary text editor.
  7592.               .ltf         The Language Translation File. This is the
  7593.                            compiled version of the .mad source file.
  7594.               .lth         The dynamic language include file for C pro-
  7595.                            grams.
  7596.               .h           The static language include file for C pro-
  7597.                            grams.
  7598.               .mh          The dynamic language include file for MEX
  7599.                            programs.
  7600.  
  7601.  
  7602.  
  7603.              For information on modifying the system language files,
  7604.              please see section 18.12.
  7605.  
  7606.  
  7607.              8.7. MAXPIPE: OS/2 Redirection Utility
  7608.  
  7609.  
  7610.              8.7.1. Description
  7611.  
  7612.              MAXPIPE is an OS/2-only program used to redirect the I/O of
  7613.              command line programs to the COM port. This program is useful
  7614.              when spawning an OS/2 shell, or when running certain programs
  7615.              that only use console I/O. (For example, Maximus-OS/2 auto-
  7616.              matically calls MAXPIPE when spawning archivers to compress
  7617.              QWK packets.)
  7618.  
  7619.              MAXPIPE also provides a "watchdog" facility. If the user
  7620.              drops carrier while the external program is active, MAXPIPE
  7621.              kills the running process and returns to Maximus.
  7622.  
  7623.  
  7624.              8.7.2. Command Line Format
  7625.  
  7626.              The command line format for MAXPIPE is:
  7627.  
  7628.                 MAXPIPE handle program [args ...]
  7629.  
  7630.              handle is the COM port handle, as generated by the "%P" ex-
  7631.              ternal program translation character. If a handle of "0" is
  7632.              used, MAXPIPE will run in local mode.
  7633.  
  7634.  
  7635.  
  7636.              8. Utility Documentation                                  135
  7637.  
  7638.              program is the name of the external program to be spawned.
  7639.              Ensure that the full filename and path is provided.
  7640.  
  7641.               [args ...] are the optional arguments to pass to the exter-
  7642.              nal program.
  7643.  
  7644.        Note! MAXPIPE works only with programs that use "stdin/stdout" out-
  7645.              put. Programs which write directly to the console (or pro-
  7646.              grams which use Presentation Manager output calls) will not
  7647.              function correctly with MAXPIPE.
  7648.  
  7649.  
  7650.              8.8. MECCA: Display File Compiler
  7651.  
  7652.  
  7653.              8.8.1. Description
  7654.  
  7655.              MECCA compiles .mec source files into binary .bbs files that
  7656.              can be displayed by Maximus. MECCA source files can contain
  7657.              human-readable tokens to change the text color, display sim-
  7658.              plistic menus and prompts, and other display-oriented tasks.
  7659.  
  7660.  
  7661.              8.8.2. Command Line Format
  7662.  
  7663.              The command line format for MECCA is:
  7664.  
  7665.                 MECCA infile [outfile] [-t] [-r]
  7666.  
  7667.              infile is the name of the input file. If no extension is
  7668.              specified, MECCA assumes .mec by default. infile can also in-
  7669.              clude wildcards.
  7670.  
  7671.              outfile is the optional output filename for the compiled
  7672.              MECCA file. This parameter is optional, and if not specified,
  7673.              it defaults to infile.bbs.
  7674.  
  7675.              The optional -t parameter instructs MECCA to compare the date
  7676.              stamps of the input and output files, and if the output file
  7677.              is newer than the input file, to skip compiling that file.
  7678.              This is useful for recompiling an entire directory of .mec
  7679.              files.
  7680.  
  7681.              The optional -r parameter instructs MECCA to produce a .rbs
  7682.              file (instead of a .bbs file) for RIPscrip graphics support.
  7683.              In addition, this switch disables RLE compression, since RLE
  7684.              can sometimes interfere with RIPscrip graphics sequences.
  7685.  
  7686.              Please see section 17 for information on the format of MECCA
  7687.              files.
  7688.  
  7689.  
  7690.  
  7691.              8. Utility Documentation                                  136
  7692.  
  7693.              8.9. MR: Maximus Renumbering Program
  7694.  
  7695.  
  7696.              8.9.1. Description
  7697.  
  7698.              MR is a *.MSG format message renumbering program. MR is not
  7699.              required if your system uses only Squish-format areas.
  7700.  
  7701.              MR automatically reads the information given in the message
  7702.              area data file, and it then renumbers, deletes and relinks
  7703.              messages in *.MSG-style areas.
  7704.  
  7705.              Renumbering is useful for eliminating large gaps in the mes-
  7706.              sage numbers of *.MSG areas (which are created when users de-
  7707.              lete messages). MR can also purge messages based on message
  7708.              age or the total number of messages in the area, allowing you
  7709.              to maintain a roughly-constant size for your message bases.
  7710.  
  7711.  
  7712.              8.9.2. Command Line Format
  7713.  
  7714.              The command line format for MR is:
  7715.  
  7716.                 mr options area [area ...]
  7717.  
  7718.              The options parameter can be zero or more of the command line
  7719.              switches shown in Table 8.6:
  7720.  
  7721.              Table 8.6 MR Command Line Switches
  7722.  
  7723.               Switch    Description
  7724.  
  7725.               -p<file>  Use the .prm file specified in <file> instead of
  7726.                         the setting in the MAXIMUS environment variable.
  7727.               -m<file>  Use <file> as the message area data file, rather
  7728.                         than using the data file specified in the .prm
  7729.                         file.
  7730.  
  7731.  
  7732.              The area parameter must include one or more area names to be
  7733.              renumbered. To renumber all areas on the system, specify an
  7734.              area of "all".
  7735.  
  7736.              For example, to renumber all message areas:
  7737.  
  7738.                 mr all
  7739.  
  7740.              To renumber message areas "muffin," "tub" and "local":
  7741.  
  7742.                 mr muffin tub local
  7743.  
  7744.  
  7745.  
  7746.              8. Utility Documentation                                  137
  7747.  
  7748.              8.9.3. Renumbering Operation
  7749.  
  7750.              When renumbering, MR will examine the Renum Days and Renum
  7751.              Max settings for each *.MSG message area. If either of those
  7752.              two keywords are set, MR will purge messages from the area
  7753.              based on the specified criteria. Messages can be killed by
  7754.              message number, by age, or both.
  7755.  
  7756.              MR automatically updates the Maximus lastread files and mes-
  7757.              sage area links. To maintain *.MSG areas, simply include a
  7758.              call to MR in your daily event batch file, and all of your
  7759.              renumbering and purging needs will be taken care of automati-
  7760.              cally.
  7761.  
  7762.  
  7763.              8.10. ORACLE: Display File Viewer
  7764.  
  7765.  
  7766.              8.10.1. Description
  7767.  
  7768.              ORACLE is an off-line .bbs file viewer that allows you to
  7769.              view compiled .bbs files without logging on. ORACLE is a
  7770.              quick way to test changes made to standard .mec files.
  7771.  
  7772.  
  7773.              8.10.2. Command Line Format
  7774.  
  7775.              The command line format for ORACLE is:
  7776.  
  7777.                 ORACLE bbsfile [options ...]
  7778.  
  7779.              bbsfile is the name of the compiled .bbs file that you wish
  7780.              to view. If no extension is supplied, .bbs is assumed.
  7781.  
  7782.              The options parameter specifies zero or more of the switches
  7783.              from Table 8.7:
  7784.  
  7785.              Table 8.7 ORACLE Command Line Switches
  7786.  
  7787.               Switch   Description
  7788.  
  7789.               -hX      Sets the current help level to X, where X is the
  7790.                        first letter of a valid help level. (N = Novice;
  7791.                        R = Regular; E = Expert.)
  7792.               -i       Disables high-bit IBM characters. When this op-
  7793.                        tion is enabled, ORACLE will automatically trans-
  7794.                        late IBM Extended ASCII to the standard ASCII
  7795.                        equivalent.
  7796.               -kX      Sets the user's keys to X, where X is a simple
  7797.                        listing of keys to assign to the user. Valid keys
  7798.                        are from 1 to 8 and A to X. For example, using
  7799.                        "-k1237AD" would give the user keys 1, 2, 3, 7, A
  7800.                        and D.
  7801.  
  7802.  
  7803.  
  7804.              8. Utility Documentation                                  138
  7805.  
  7806.               -mX      Sets the local video mode to X, where X is a
  7807.                        valid video mode. (B = BIOS; I = IBM.) This only
  7808.                        applies to the DOS version of Maximus.
  7809.               -pX      Reads the Maximus .prm information from the file
  7810.                        X. This setting will override the MAXIMUS envi-
  7811.                        ronment variable.
  7812.               -q       This option enables hotkeys mode.
  7813.               -slX     This option sets the virtual screen length to X
  7814.                        rows. This does not change your physical screen
  7815.                        length; however, it does tell Maximus when to
  7816.                        display "More [Y,n,=]?" prompts. The default
  7817.                        screen length is 24 lines.
  7818.               -swX     This option sets the virtual screen width to X
  7819.                        columns. This does not change your physical
  7820.                        screen width; however, it controls when virtual
  7821.                        screen wraps occur.
  7822.               -t       The -t parameter forces ORACLE into TTY video
  7823.                        mode. This disables all ANSI and AVATAR graphics
  7824.                        commands, and ORACLE displays files just as they
  7825.                        would be shown to a TTY caller.
  7826.               -vX      This sets the user's privilege level to X, where
  7827.                        X is either a numeric privilege level or a user
  7828.                        class abbreviation.
  7829.  
  7830.  
  7831.              Settings from the ORACLE command line can also be set perma-
  7832.              nently using an environment variable. By issuing a "SET ORA-
  7833.              CLE=" command, you can create a set of defaults for every
  7834.              file that you view with ORACLE:
  7835.  
  7836.              For example, issuing the following sequence of commands:
  7837.  
  7838.                 SET ORACLE=-v100 -q
  7839.                 ORACLE D:\Max\Misc\Bulletin
  7840.  
  7841.              is identical to entering all of this at once:
  7842.  
  7843.                 ORACLE D:\Max\Misc\Bulletin -v100 -q
  7844.  
  7845.              Although the first example looks like more typing, you can
  7846.              easily place the SET command into your autoexec.bat (DOS) or
  7847.              config.sys (OS/2), and then only type "oracle <filename>"
  7848.              whenever you want to display a file.
  7849.  
  7850.  
  7851.              8.11. SCANBLD: *.MSG Database Builder
  7852.  
  7853.              SCANBLD builds databases of *.MSG-format message areas.
  7854.              SCANBLD is not required if your system uses only Squish-
  7855.              format areas.
  7856.  
  7857.              The primary function of SCANBLD is to speed up the internal
  7858.              Maximus mailchecker and Msg_Browse commands. Accessing mes-
  7859.  
  7860.  
  7861.  
  7862.              8. Utility Documentation                                  139
  7863.  
  7864.              sages in *.MSG areas is very slow, so SCANBLD builds an index
  7865.              of the messages in each message area to decrease processing
  7866.              time.
  7867.  
  7868.              SCANBLD must be run after certain events occur, including af-
  7869.              ter running a message renumbering utility, after receiving
  7870.              EchoMail, after a user enters a message, and so on. Running
  7871.              these commands is somewhat inconvenient, but SCANBLD is re-
  7872.              quired for SysOps who still insist on running *.MSG-format
  7873.              message areas.
  7874.  
  7875.  
  7876.              8.11.1. Command Line Format
  7877.  
  7878.              The command line format for SCANBLD is:
  7879.  
  7880.                 SCANBLD [switches...] [area...] [!area...]
  7881.                   [All | Local | Matrix | Echo | Conf |
  7882.                   @tosslog]
  7883.  
  7884.              The optional switches parameter can specify any of the com-
  7885.              mand line switches from Table 8.8 below:
  7886.  
  7887.              Table 8.8 SCANBLD Command Line Switches
  7888.  
  7889.               Switch      Description
  7890.  
  7891.               -c          Instructs SCANBLD to do a full compile of each
  7892.                           area processed. By default, SCANBLD will try
  7893.                           to update the mail database in the areas proc-
  7894.                           essed, without necessarily rebuilding the en-
  7895.                           tire area. The -c switch should always be used
  7896.                           after renumbering a message area.
  7897.               -m<file>    Use the message area data file specified by
  7898.                           file, rather than using the default data file
  7899.                           specified in the .prm file.
  7900.               -nd         Instructs SCANBLD to not delete the @tosslog
  7901.                           filename after processing the entries within.
  7902.                           This is useful if you have other utilities
  7903.                           which need the tosslog after SCANBLD has fin-
  7904.                           ished.
  7905.               -p<file>    Use the .prm file specified by file, rather
  7906.                           than using the setting in the MAXIMUS environ-
  7907.                           ment variable.
  7908.               -q          Quiet mode. Instead of displaying the statis-
  7909.                           tics for each area, display a single hash sign
  7910.                           ("#") instead.
  7911.               -u<file>    Use the user file specified by <file>, rather
  7912.                           than the default user file specified in the
  7913.                           .prm file.
  7914.  
  7915.  
  7916.  
  7917.              8. Utility Documentation                                  140
  7918.  
  7919.              The remainder of the SCANBLD command line contains a list of
  7920.              areas (or types of areas) to process:
  7921.  
  7922.              If you specify All, SCANBLD will rebuild the database for all
  7923.              message areas.
  7924.  
  7925.              If you specify Local, SCANBLD will rebuild the database for
  7926.              local message areas only.
  7927.  
  7928.              If you specify Matrix, SCANBLD will rebuild the database for
  7929.              NetMail areas only.
  7930.  
  7931.              If you specify Echo, SCANBLD will rebuild the database for
  7932.              EchoMail areas only.
  7933.  
  7934.              If you specify Conf, SCANBLD will rebuild the database for
  7935.              Conference areas only.
  7936.  
  7937.              If you specify @tosslog, SCANBLD will read the file specified
  7938.              by tosslog and read a list of area tags from within. SCANBLD
  7939.              will rebuild message areas which have a Tag keyword that
  7940.              matches one of the tags specified in the tosslog file.
  7941.  
  7942.              If you specify the name of an area on the command line,
  7943.              SCANBLD will rebuild the message database for that area.
  7944.  
  7945.              If you specify !area on the command line, SCANBLD will ex-
  7946.              plicitly skip the specified message area, even if it was in-
  7947.              cluded by another command line parameter. (This option is
  7948.              useful in conjunction with the "All," "Local," "Matrix," and
  7949.              other related keywords.)
  7950.  
  7951.  
  7952.              8.11.2. Examples
  7953.  
  7954.              The options specified on the SCANBLD command line are cumula-
  7955.              tive, so entering the following:
  7956.  
  7957.                 scanbld echo matrix 45 !22 @et.log
  7958.  
  7959.              causes SCANBLD to process all EchoMail and NetMail areas
  7960.              (except for area 22), in addition to area number 45 and the
  7961.              areas listed in et.log.
  7962.  
  7963.              To ensure that the mail database is always synchronized with
  7964.              your message base, you should run SCANBLD as follows:
  7965.  
  7966.              After a user enters EchoMail (usually errorlevel 12):
  7967.  
  7968.                 SCANBLD local matrix @et.log
  7969.  
  7970.              After a user enters NetMail (usually errorlevel 11):
  7971.  
  7972.  
  7973.  
  7974.              8. Utility Documentation                                  141
  7975.  
  7976.                 SCANBLD local matrix
  7977.  
  7978.              After a user enters local mail (usually errorlevel 5):
  7979.  
  7980.                 SCANBLD local
  7981.  
  7982.              After importing EchoMail:
  7983.  
  7984.                 SCANBLD local matrix @et.log
  7985.  
  7986.              After running any message-renumbering utility:
  7987.  
  7988.                 SCANBLD all /c
  7989.  
  7990.              Finally, if you use an external message editor to access
  7991.              *.MSG areas, you must run SCANBLD over all areas that were
  7992.              modified by the editor. If your editor produces an echo-
  7993.              toss.log-like file, run SCANBLD after your editor using the
  7994.              command shown for "After a user enters EchoMail."
  7995.  
  7996.              However, if your external editor does not produce an echo-
  7997.              toss.log (or similar) file, you must scan all areas using the
  7998.              following command:
  7999.  
  8000.                 SCANBLD all
  8001.  
  8002.              If these instructions are not followed to the letter, SCANBLD
  8003.              may miss messages for your users which would be otherwise be
  8004.              flagged as new mail.
  8005.  
  8006.  
  8007.              8.12. SILT: Control File Compiler
  8008.  
  8009.  
  8010.              8.12.1. Description
  8011.  
  8012.              SILT is the Maximus control file compiler. SILT compiles the
  8013.              raw ASCII control files into the binary parameter files that
  8014.              are used by Maximus. You must run SILT every time you make a
  8015.              change to one of the Maximus control files.
  8016.  
  8017.  
  8018.              8.12.2. Command Line Format
  8019.  
  8020.              The SILT command line format is:
  8021.  
  8022.                 SILT ctl_file [switches]
  8023.  
  8024.              ctl_file is the name of the control file to be compiled
  8025.              (without an extension). By default, if no parameters other
  8026.              than ctl_file are specified, Maximus will compile all fea-
  8027.              tures in the control file. (However, it will not generate the
  8028.              Maximus 2.x-compatible area.dat by default.)
  8029.  
  8030.  
  8031.  
  8032.              8. Utility Documentation                                  142
  8033.  
  8034.              The optional switches parameter can specify zero or more of
  8035.              the command line switches from Table 8.9:
  8036.  
  8037.              Table 8.9 SILT Command Line Switches
  8038.  
  8039.               Switch    Description
  8040.  
  8041.               -2a       Create a Maximus 2.x-compatible area.dat file.
  8042.                         Area names are truncated to 10 characters.
  8043.               -2u       Create a Maximus 2.x-compatible area.dat file.
  8044.                         Area names are truncated to 10 characters, but
  8045.                         dots (".") are converted to underscores ("_").
  8046.               -2s       Create a Maximus 2.x-compatible area.dat file.
  8047.                         Only the last part of the area name (after the
  8048.                         last dot) is written for message and file areas
  8049.                         within divisions.
  8050.               -a        Compile message and file areas only.
  8051.               -am       Compile only message areas.
  8052.               -af       Compile only file areas.
  8053.               -m        Compile only menu definitions.
  8054.               -p        Compile only the system control files (and the
  8055.                         other control files required for max.prm).
  8056.               -u        Run in "unattended mode." SILT will automati-
  8057.                         cally create directories that do not exist, and
  8058.                         it will not pause for user input.
  8059.               -x        Compile everything (default).
  8060.  
  8061.  
  8062.              8.13. SM: Session Monitor
  8063.  
  8064.  
  8065.              8.13.1. Description
  8066.  
  8067.         OS/2 Session Monitor (SM) is a Presentation Manager program for
  8068.        only! Maximus-OS/2 SysOps. SM works in conjunction with MCP to al-
  8069.              low SysOps to view and manipulate remote Maximus sessions,
  8070.              either on the local machine or across a LAN.
  8071.  
  8072.  
  8073.              8.13.2. Command Line Format
  8074.  
  8075.              SM has the following command line format:
  8076.  
  8077.                 sm
  8078.  
  8079.              No command line parameters are supported.
  8080.  
  8081.  
  8082.              8.13.3. Using SM
  8083.  
  8084.              When SM is started, it will read information about your sys-
  8085.              tem from the .prm file specified by the MAXIMUS environment
  8086.              variable. It will then attempt to connect to the MCP server
  8087.  
  8088.  
  8089.  
  8090.              8. Utility Documentation                                  143
  8091.  
  8092.              specified by the MCP Pipe definition in the system control
  8093.              file. SM can connect to a MCP server on a local machine, and
  8094.              if the MCP Pipe definition points to a network server, SM can
  8095.              also connect to a MCP server running on another machine.
  8096.  
  8097.              Once connected to the MCP server, SM displays a system over-
  8098.              view. For each node, SM will display:
  8099.  
  8100.              *  The name of the user on that node, or "(off-line)" if Maxi-
  8101.                 mus is not running.
  8102.  
  8103.              *  The status of the user (such as "Transferring a file" or
  8104.                 "Available for chat").
  8105.  
  8106.              *  The last "ping" time. All Maximus nodes will send a "ping"
  8107.                 to the MCP server at a predefined interval. If the MCP
  8108.                 server does not receive a ping from a Maximus node for a
  8109.                 certain period of time, it will highlight the ping time in
  8110.                 red. This indicates that there may be trouble on the indi-
  8111.                 cated node.
  8112.  
  8113.              To interact with a Maximus node, select the node with the
  8114.              mouse and press mouse button 2. If a user is logged on, a
  8115.              pop-up menu will present the following options:
  8116.  
  8117.              *  View. This option allows you to view the screen for the se-
  8118.                 lected node. The screen may not be displayed properly if
  8119.                 the node is in WFC mode or if the caller is running an ex-
  8120.                 ternal program.
  8121.  
  8122.              *  Message. This option allows you to send a message to the
  8123.                 user logged onto the node.
  8124.  
  8125.              *  Global>Message. This option allows you to send a message to
  8126.                 all active Maximus nodes.
  8127.  
  8128.  
  8129.  
  8130.  
  8131.  
  8132.  
  8133.  
  8134.  
  8135.                                                 9. REXX User File Interface
  8136.  
  8137.  
  8138.              9.1. Introduction
  8139.  
  8140.         OS/2 Maximus-OS/2 includes a REXX User File Application Program-
  8141.        only! ming Interface (API). This API allows programs written in
  8142.              REXX to scan the user file, read user information for par-
  8143.              ticular users, update fields in existing user records, and
  8144.              add new users.
  8145.  
  8146.              To use the REXX API, the maxuapi.dll file must be on your
  8147.              system's LIBPATH, and the following prologue must be inserted
  8148.              at the beginning of the REXX program:
  8149.  
  8150.                 /* rexx */
  8151.  
  8152.                 call RxFuncAdd 'MaxLoadFuncs', 'MAXUAPI', 'MaxLoadFuncs'
  8153.                 call MaxLoadFuncs
  8154.  
  8155.              This code instructs the REXX interpreter to load a copy of
  8156.              maxuapi.dll and to import all of the REXX user file API func-
  8157.              tions.
  8158.  
  8159.              Table 9.1 lists the functions supported by the REXX user file
  8160.              API:
  8161.  
  8162.              Table 9.1 REXX User API Functions
  8163.  
  8164.               Function              Description
  8165.  
  8166.               MaxLoadFuncs          Load all of the user file API func-
  8167.                                     tions into the REXX namespace.
  8168.               MaxUnloadFuncs        Unload all of the user file API
  8169.                                     functions
  8170.               UserFileClose         Close the user file. This function
  8171.                                     must be called when a REXX program
  8172.                                     is finished accessing the user file.
  8173.               UserFileCreateRecord  Create a new record in the user
  8174.                                     file.
  8175.               UserFileFind          Find a single user within the user
  8176.                                     file.
  8177.               UserFileFindClose     Terminate a multi-user find session.
  8178.               UserFileFindNext      Find the next user in a multi-user
  8179.                                     find session.
  8180.               UserFileFindOpen      Begin a multi-user find session.
  8181.               UserFileFindPrior     Find the previous user in a multi-
  8182.                                     user find session.
  8183.               UserFileGetNewLastrea Obtain a lastread pointer for a new
  8184.               d                     user.
  8185.  
  8186.  
  8187.  
  8188.              9. REXX User File Interface                               146
  8189.  
  8190.               UserFileInitRecord    Initialize the "usr." stem variable.
  8191.               UserFileOpen          Open a user file.
  8192.               UserFileSize          Retrieves the number of records
  8193.                                     stored in the user file.
  8194.               UserFileUpdate        Updates (commits) changes to an ex-
  8195.                                     isting user record.
  8196.  
  8197.  
  8198.              For examples of using the REXX user file API, please see the
  8199.              sample *.cmd files that are distributed with Maximus.
  8200.  
  8201.  
  8202.              9.2. Function Descriptions
  8203.  
  8204.              This section describes all of the functions supported in the
  8205.              REXX user file API.
  8206.  
  8207.  
  8208.  
  8209.              MaxLoadFuncs
  8210.  
  8211.  
  8212.  
  8213.  
  8214.  Prototype   call MaxLoadFuncs
  8215.  
  8216.  Description The MaxLoadFuncs procedure loads all of the user file API
  8217.              functions into memory. This procedure must be called before
  8218.              any of the other API functions can be used.
  8219.  
  8220.              Note that the MaxLoadFuncs procedure must also be loaded into
  8221.              memory before it can be called. To load the MaxLoadFuncs pro-
  8222.              cedure (followed by the rest of the user file API functions),
  8223.              use the following REXX code:
  8224.  
  8225.                 /* rexx */
  8226.  
  8227.                 call RxFuncAdd 'MaxLoadFuncs', 'MAXUAPI', 'MaxLoadFuncs'
  8228.                 call MaxLoadFuncs
  8229.  
  8230.  
  8231.  
  8232.              MaxUnloadFuncs
  8233.  
  8234.  
  8235.  
  8236.  
  8237.  Prototype   call MaxUnloadFuncs
  8238.  
  8239.  Description This procedure unloads all of the user file API functions
  8240.              from memory. MaxUnloadFuncs should be called at the end of a
  8241.              command file that contains calls to the user file API func-
  8242.              tions.
  8243.  
  8244.  
  8245.  
  8246.              9. REXX User File Interface                               147
  8247.  
  8248.  
  8249.              UserFileClose
  8250.  
  8251.  
  8252.  
  8253.  
  8254.  Prototype   rc=UserFileClose(huf)
  8255.  
  8256.  Arguments   huf is the handle of the user file to close, as returned by
  8257.              UserFileOpen.
  8258.  
  8259.  Return Val. If the user file was closed successfully, this function re-
  8260.              turns "1". Otherwise, the return value is "0".
  8261.  
  8262.  Description This function must be called at the end of your REXX program
  8263.              to close the user file. Failure to call UserFindClose may
  8264.              cause data to be lost.
  8265.  
  8266.              After calling UserFindClose, the handle returned by User-
  8267.              FileOpen is no longer valid.
  8268.  
  8269.  
  8270.  
  8271.              UserFileCreateRecord
  8272.  
  8273.  
  8274.  
  8275.  
  8276.  Prototype   rc=UserFileCreateRecord(huf)
  8277.  
  8278.  Arguments   huf must be a user file handle returned by UserFileFindOpen.
  8279.  
  8280.  Return Val. This function returns "1" if the user record was created suc-
  8281.              cessfully, or "0" otherwise.
  8282.  
  8283.  Description The "usr." stem variable must be filled out (as a minimum)
  8284.              with the new user's name and alias. The user record in this
  8285.              structure will be added to the specified user file as a new
  8286.              user record.
  8287.  
  8288.              Ideally, your program should first call the UserFileInitRe-
  8289.              cord function to initialize the "usr." stem variable. Next,
  8290.              your program should call UserFileGetNewLastread to obtain a
  8291.              new lastread pointer for the user. Finally, your program
  8292.              should fill out the "usr.name" and "usr.alias" variables,
  8293.              along with any other desired settings.
  8294.  
  8295.  
  8296.  
  8297.              9. REXX User File Interface                               148
  8298.  
  8299.  
  8300.              UserFileFind
  8301.  
  8302.  
  8303.  
  8304.  
  8305.  Prototype   rc=UserFileFind(huf, name, alias)
  8306.  
  8307.  Arguments   huf specifies a user file handle, as returned by
  8308.              UserFileOpen.
  8309.  
  8310.              name specifies the name of the user to find. If this field is
  8311.              blank, the user's name is ignored when trying to find a
  8312.              match.
  8313.  
  8314.              alias specifies the alias of the user to find. If this field
  8315.              is blank, the user's alias is ignored when trying to find a
  8316.              match.
  8317.  
  8318.  Return Val. This function returns "1" if the specified user was found;
  8319.              otherwise, it returns "0".
  8320.  
  8321.  Description When UserFileFind successfully finds a user, it places all of
  8322.              the information related to that user in the "usr." stem vari-
  8323.              able. For information on accessing these fields, please see
  8324.              section 9.3.
  8325.  
  8326.              This function tries to find a single user in the user file.
  8327.              If both name and alias are non-blank, UserFileFind only tries
  8328.              to find a user record that matches both the name and alias
  8329.              fields.
  8330.  
  8331.              If name is specified but alias is an empty string, UserFile-
  8332.              Find ignores the alias field and only tries to find a user
  8333.              whose name matches name.
  8334.  
  8335.              If alias is specified but name is an empty string, UserFile-
  8336.              Find ignores the name field and only tries to find a user
  8337.              whose alias matches alias.
  8338.  
  8339.              If both name and alias are empty strings, UserFileFind re-
  8340.              turns the first user in the user file.
  8341.  
  8342.  
  8343.  
  8344.              UserFileFindClose
  8345.  
  8346.  
  8347.  
  8348.  
  8349.  Prototype   rc=UserFileFindClose(huff)
  8350.  
  8351.  
  8352.  
  8353.              9. REXX User File Interface                               149
  8354.  
  8355.  Prototype   huff is a user file find handle returned from UserFileFin-
  8356.              dOpen.
  8357.  
  8358.  Return Val. This function returns "1" if the user find handle was closed
  8359.              successfully, or "0" otherwise.
  8360.  
  8361.  Description This function must be called to deallocate the memory and
  8362.              files associated with a user file finding operation.
  8363.  
  8364.  
  8365.  
  8366.              UserFileFindNext
  8367.  
  8368.  
  8369.  
  8370.  
  8371.  Prototype   rc=UserFileFindNext(huff, name, alias)
  8372.  
  8373.  Arguments   huff is the user file find handle, as returned by UserFile-
  8374.              FindOpen.
  8375.  
  8376.              name specifies the next name to look for in a sequential
  8377.              search of the user file. A blank string matches the next
  8378.              available user name.
  8379.  
  8380.              alias specifies the next alias to look for in a sequential
  8381.              search of the user file. A blank string matches the next
  8382.              available user alias.
  8383.  
  8384.  Return Val. If a user matching the specified criteria was found, this
  8385.              function returns "1" and stores the user's information in the
  8386.              "usr." stem variable. If no user was found, this function re-
  8387.              turns "0".
  8388.  
  8389.  Description This function returns the next user in a UserFileFindOpen
  8390.              search. The name and alias parameters do not need to be the
  8391.              same as specified in the original UserFileFindOpen call.
  8392.  
  8393.  
  8394.  
  8395.              UserFileFindOpen
  8396.  
  8397.  
  8398.  
  8399.  
  8400.  Prototype   huff = UserFileFindOpen(huf, name, alias)
  8401.  
  8402.  Arguments   huf is the user file handle returned by UserFileOpen.
  8403.  
  8404.  Arguments   name is the name of the user to find, or a blank string to
  8405.              match any user name.
  8406.  
  8407.  
  8408.  
  8409.              9. REXX User File Interface                               150
  8410.  
  8411.              alias is the alias of the user to find, or a blank string to
  8412.              match any alias.
  8413.  
  8414.  Return Val. If a user matching the name/alias criteria is found, this
  8415.              function returns a positive handle for the search operation.
  8416.              If no matching users were found, this function returns "-1".
  8417.  
  8418.  Description If a user is found, the "usr." stem variable is filled out
  8419.              with the information in the user record. The UserFileFindNext
  8420.              function can be called to find subsequent users.
  8421.  
  8422.              The name and alias parameters should be specified using the
  8423.              same rules as given for UserFileFind.
  8424.  
  8425.  
  8426.  
  8427.              UserFileFindPrior
  8428.  
  8429.  
  8430.  
  8431.  
  8432.  Prototype   rc=UserFileFindPrior(huff, name, alias)
  8433.  
  8434.  Arguments   huff is the user file find handle, as returned by UserFile-
  8435.              FindOpen.
  8436.  
  8437.              name specifies the next name to look for in a reverse sequen-
  8438.              tial search of the user file. A blank string matches the user
  8439.              prior to the current record.
  8440.  
  8441.              alias specifies the next alias to look for in a reverse se-
  8442.              quential search of the user file. A blank string matches the
  8443.              user prior to the current record.
  8444.  
  8445.  Return Val. If a user matching the specified criteria was found, this
  8446.              function returns "1" and stores the user's information in the
  8447.              "usr." stem variable. If no user was found, this function re-
  8448.              turns "0".
  8449.  
  8450.  Description This function performs the same function as UserFileFindNext,
  8451.              except that the search starts at the current user record and
  8452.              searches backward to the beginning of the user file.
  8453.  
  8454.  
  8455.  
  8456.              UserFileGetNewLastread
  8457.  
  8458.  
  8459.  
  8460.  
  8461.  Prototype   usr.lastread_ptr = UserFileGetNewLastread(huf)
  8462.  
  8463.  Arguments   huf must be a user file handle returned by UserFileOpen.
  8464.  
  8465.  
  8466.  
  8467.              9. REXX User File Interface                               151
  8468.  
  8469.  Return Val. This function returns the next available lastread pointer in
  8470.              the user file.
  8471.  
  8472.  Description This function should be used to obtain a lastread pointer
  8473.              when creating a new user record.
  8474.  
  8475.  
  8476.  
  8477.              UserFileInitRecord
  8478.  
  8479.  
  8480.  
  8481.  
  8482.  Prototype   call UserFileInitRecord(huf)
  8483.  
  8484.  Arguments   huf must be a user file handle returned by a call to User-
  8485.              FileOpen.
  8486.  
  8487.  Description This function initializes the REXX "usr.*" stem variable to a
  8488.              set of standard values. This function can be called before
  8489.              filling out a user record for a new user.
  8490.  
  8491.  
  8492.  
  8493.              UserFileOpen
  8494.  
  8495.  
  8496.  
  8497.  
  8498.  Prototype   huf = UserFileOpen(userfile, mode)
  8499.  
  8500.  Arguments   userfile is the path and root filename of the Maximus user
  8501.              file, without the extension. In a typical Maximus installa-
  8502.              tion, this field is "\max\user".
  8503.  
  8504.              mode is the file opening mode to use when opening the user
  8505.              file. If mode is "create" the user file will be created only
  8506.              if it does not exist. Otherwise, if the mode is not "create"
  8507.              (or if the user file already exists), the existing user file
  8508.              is opened in read/write mode.
  8509.  
  8510.  Return Val. On success, UserFileOpen returns a handle for the user file.
  8511.              This handle must be passed to all future UserFile* functions.
  8512.              If the user file could not be opened, this function returns
  8513.              "-1".
  8514.  
  8515.  Description This function open the Maximus user file for interaction. Us-
  8516.              erFileOpen must be called before accessing any of the other
  8517.              REXX API functions.
  8518.  
  8519.              The user file may not necessarily be called user.bbs. It is
  8520.              best to allow the name of the user file to be passed as an
  8521.              argument to your REXX program.
  8522.  
  8523.  
  8524.  
  8525.              9. REXX User File Interface                               152
  8526.  
  8527.              This function must be called before any of the other user
  8528.              file functions can be used. The value returned by this func-
  8529.              tion should be stored in a variable so that it can be passed
  8530.              as the argument to the other UserFile* functions.
  8531.  
  8532.  
  8533.  
  8534.              UserFileSize
  8535.  
  8536.  
  8537.  
  8538.  
  8539.  Prototype   size = UserFileSize(huf)
  8540.  
  8541.  Arguments   huf is the user file handle, as returned by the UserFileOpen
  8542.              call
  8543.  
  8544.  Return Val. This function returns the number of users in the user file,
  8545.              or -1 if an invalid user file handle was provided.
  8546.  
  8547.  Description This function counts the number of users in the specified
  8548.              user file.
  8549.  
  8550.  
  8551.  
  8552.              UserFileUpdate
  8553.  
  8554.  
  8555.  
  8556.  
  8557.  Prototype   rc=UserFileUpdate(huf, name, alias)
  8558.  
  8559.  Arguments   huf is a user file handle returned from UserFileOpen.
  8560.  
  8561.              name is the name of the user to modify. This parameter is not
  8562.              optional.
  8563.  
  8564.              alias specifies the alias of the user to modify. This parame-
  8565.              ter is not optional.
  8566.  
  8567.  Return Val. This function returns "1" if the update was successful, or
  8568.              "0" otherwise.
  8569.  
  8570.  Description This function takes the user information stored in the "usr."
  8571.              stem variable and writes it into the user record for the
  8572.              named user. If the specified user does not exist, this func-
  8573.              tion will fail.
  8574.  
  8575.              The name and alias parameters must specify the name and alias
  8576.              of the user, as it currently exists in the user file. In most
  8577.              cases, these will simply be "usr.name" and "usr.alias". How-
  8578.              ever, in cases where the REXX program modifies the user's
  8579.  
  8580.  
  8581.  
  8582.              9. REXX User File Interface                               153
  8583.  
  8584.              name or alias, these fields must point to the user record's
  8585.              original name and alias.
  8586.  
  8587.  
  8588.              9.3. Accessing "usr." Variables
  8589.  
  8590.              All of the fields in the user record are exported to the REXX
  8591.              namespace using the "usr." stem variable. Most of these vari-
  8592.              ables are exported as strings, but some are stored as binary
  8593.              variables.
  8594.  
  8595.              Table 9.2 lists the types that are used to store various
  8596.              parts of the user record.
  8597.  
  8598.              Table 9.2 REXX Types
  8599.  
  8600.               Type       Description
  8601.  
  8602.               string     This variable represents a variable-length
  8603.                          string. If a maximum length is imposed on the
  8604.                          string, this is indicated in square brackets
  8605.                          beside the type name.
  8606.  
  8607.               char       This variable represents an 8-bit integer. Any
  8608.                          number in the range -128 to 127 is valid.
  8609.  
  8610.               int        This variable represents a 16-bit integer. Any
  8611.                          number in the range -32768 to 32767 is valid.
  8612.  
  8613.               long       This variable represents a 32-bit integer. Any
  8614.                          number in the range -2147483648 to 2147483647
  8615.                          is valid.
  8616.  
  8617.               bool       This variable represents a boolean value. The
  8618.                          character "Y" represents YES; the character "N"
  8619.                          represents NO. No other values are valid.
  8620.  
  8621.               priv       This variable represents a privilege level.
  8622.                          Values in the range 0 through 65535 are valid.
  8623.  
  8624.               help       This variable represents a help level. This
  8625.                          field can contain any of the following values:
  8626.                          "Novice", "Regular", or "Expert".
  8627.  
  8628.               video      This variable represents a video mode. This
  8629.                          field can contain any of the following values:
  8630.                          "TTY", "ANSI", or "AVATAR".
  8631.  
  8632.               date       This variable represents a date. If the date is
  8633.                          modified, it must be stored in exactly this
  8634.                          format:
  8635.  
  8636.                             dd mmm yy hh:mm:ss
  8637.  
  8638.  
  8639.  
  8640.              9. REXX User File Interface                               154
  8641.  
  8642.  
  8643.                          dd is the two-digit, zero-padded day of month
  8644.                          (01-31).
  8645.  
  8646.                          mmm is the three-character abbreviation for the
  8647.                          month name. This field must be one of "Jan",
  8648.                          "Feb", "Mar", ..., "Dec".
  8649.  
  8650.                          yy is the last two digits of the current year
  8651.                          ("95").
  8652.  
  8653.                          hh, mm and ss represent the hours, minutes and
  8654.                          seconds in 24-hour time.
  8655.  
  8656.                          All of these two-digit numbers should be zero
  8657.                          padded such that "1" through "9" become "01" to
  8658.                          "09".
  8659.  
  8660.                          For example: "09 Jul 95 06:15:02"
  8661.  
  8662.               keys       This variable contains a list of keys held by
  8663.                          the user. All of the standard Maximus key val-
  8664.                          ues can be enabled by simply listing those val-
  8665.                          ues in the string. All keys from 1 to 8 and A
  8666.                          to X are valid.
  8667.  
  8668.                          The keys need not be placed in the string in
  8669.                          any particular order. For example, if a user
  8670.                          had keys A, B, F, 3 and 6, the keys string
  8671.                          could be set to "ABF36". Any other permutation
  8672.                          (such as "6FB3A") is also treated identically.
  8673.  
  8674.  
  8675.  
  8676.  
  8677.              Table 9.3 lists the fields made available to the REXX program
  8678.              after a call to UserFileFind, UserFileFindNext, or UserFile-
  8679.              FindPrior. All of these variables are stored under the "usr."
  8680.              stem variable. For example, to access the "city" field, your
  8681.              REXX program must reference "usr.city".
  8682.  
  8683.              Table 9.3 REXX User Record Structure
  8684.  
  8685.               Name          Type         Description
  8686.  
  8687.               num           int          The user number of the current
  8688.                                          user. This variable must not be
  8689.                                          modified.
  8690.  
  8691.               name          string[35]   The primary log-on name of the
  8692.                                          given user.
  8693.  
  8694.  
  8695.  
  8696.              9. REXX User File Interface                               155
  8697.  
  8698.               city          string[35]   The user's "city" or location.
  8699.  
  8700.               alias         string[20]   The user's alias or secondary
  8701.                                          log-on name.
  8702.  
  8703.               phone         string[15]   The user's phone number.
  8704.  
  8705.               lastread_ptr  int          The user's lastread pointer
  8706.                                          offset. For new users, this
  8707.                                          field can be filled in by call-
  8708.                                          ing UserFileGetNewLastread.
  8709.  
  8710.               timeremainin  int          The number of minutes that the
  8711.               g                          user had remaining when he/she
  8712.                                          last logged off.
  8713.  
  8714.               pwd           string[15]   This is the user's password.
  8715.  
  8716.                                          WARNING! If the "encrypt" field
  8717.                                          (below) is set to "Y", the
  8718.                                          password field is stored as a
  8719.                                          16-byte encrypted string which
  8720.                                          cannot be displayed. Otherwise,
  8721.                                          if the "encrypt" field is set
  8722.                                          to "N", the password is stored
  8723.                                          in plaintext and can be dis-
  8724.                                          played as a normal string.
  8725.  
  8726.                                          There are no facilities avail-
  8727.                                          able in REXX for manipulating
  8728.                                          encrypted passwords, so care
  8729.                                          should be taken when updating
  8730.                                          this field.
  8731.  
  8732.                                          To assign a new password to a
  8733.                                          user, set the "pwd" field to
  8734.                                          the plaintext password, and en-
  8735.                                          sure that the "encrypt" field
  8736.                                          is set to "N".
  8737.  
  8738.                                          Note that Maximus will auto-
  8739.                                          matically convert the password
  8740.                                          to an encrypted format the next
  8741.                                          time it accesses the user rec-
  8742.                                          ord.
  8743.  
  8744.               times         int          The number of times that the
  8745.                                          user has called the system.
  8746.  
  8747.               help          help         The user's current help set-
  8748.                                          ting.
  8749.  
  8750.  
  8751.  
  8752.              9. REXX User File Interface                               156
  8753.  
  8754.               video         video        The user's current video set-
  8755.                                          ting.
  8756.  
  8757.               nulls         char         The number of NULs sent after
  8758.                                          each end-of-line character.
  8759.  
  8760.               hotkeys       bool         The user's hotkeys setting.
  8761.  
  8762.               notavail      bool         If this is set to "Y", the user
  8763.                                          cannot be paged for multinode
  8764.                                          chats.
  8765.  
  8766.               fsr           bool         If this is set to "Y", the
  8767.                                          full-screen reader is enabled.
  8768.  
  8769.               nerd          bool         If this is set to "Y", the
  8770.                                          user's yells are silenced.
  8771.  
  8772.               noulist       bool         If this is set to "Y", the user
  8773.                                          will not be displayed in the
  8774.                                          standard user list.
  8775.  
  8776.               tabs          bool         If this is set to "Y", groups
  8777.                                          of 8 spaces will be sent to the
  8778.                                          user as tabs.
  8779.  
  8780.               encrypt       bool         If this is set to "Y", the
  8781.                                          user's "pwd" field is currently
  8782.                                          stored in an encrypted format.
  8783.                                          Otherwise, the password is
  8784.                                          stored as plaintext.
  8785.  
  8786.               rip           bool         If this is set to "Y", RIPscrip
  8787.                                          graphics are enabled.
  8788.  
  8789.               badlogon      bool         If this is set to "Y", Max will
  8790.                                          behave as if the user entered
  8791.                                          an incorrect password on the
  8792.                                          last log-on attempt.
  8793.  
  8794.               ibmchars      bool         If this is set to "Y", Max will
  8795.                                          send high-bit IBM extended AS-
  8796.                                          CII characters directly to the
  8797.                                          user. Otherwise, it will at-
  8798.                                          tempt to translate those char-
  8799.                                          acters to 7-bit equivalents.
  8800.  
  8801.               bored         bool         If this is set to "Y", the
  8802.                                          BORED line editor is enabled.
  8803.                                          Otherwise, the MaxEd full-
  8804.                                          screen editor is enabled.
  8805.  
  8806.  
  8807.  
  8808.              9. REXX User File Interface                               157
  8809.  
  8810.               more          bool         If this is set to "Y", the user
  8811.                                          will receive "More [Y,n,=]?"
  8812.                                          prompts after every page of
  8813.                                          output.
  8814.  
  8815.               configured    bool         If this is set to "Y", Maximus
  8816.                                          has already asked the user the
  8817.                                          introductory log-on questions,
  8818.                                          such as "Use ANSI?", "Use
  8819.                                          MaxEd?", and so on.
  8820.  
  8821.               cls           bool         If this is set to "Y", the user
  8822.                                          wants screen-clearing codes to
  8823.                                          be sent.
  8824.  
  8825.               priv          priv         The user's current privilege
  8826.                                          level.
  8827.  
  8828.               time          int          The number of minutes for which
  8829.                                          the user was on-line, between
  8830.                                          00:00 and 23:59, on the date
  8831.                                          specified by usr.ludate.
  8832.  
  8833.               deleted       bool         If this flag is set to "Y", the
  8834.                                          user is marked as deleted.
  8835.  
  8836.               permanent     bool         If this flag is set to "Y", the
  8837.                                          user is marked as permanent.
  8838.                                          (This means that the user can-
  8839.                                          not be deleted by automated
  8840.                                          purging programs.)
  8841.  
  8842.               width         char         The width of the caller's
  8843.                                          screen.
  8844.  
  8845.               len           char         The height of the caller's
  8846.                                          screen.
  8847.  
  8848.               credit        int          The user's credit value for
  8849.                                          NetMail messages.
  8850.  
  8851.               debit         int          The user's debit value for Net-
  8852.                                          Mail messages. The user's Net-
  8853.                                          Mail balance can be calculated
  8854.                                          using this formula:
  8855.  
  8856.                                          balance = credit - debit
  8857.  
  8858.               xp_priv       priv         The privilege level to which
  8859.                                          the user will be demoted when
  8860.                                          the user's subscription ex-
  8861.                                          pires. The user will only be
  8862.                                          demoted to this value if
  8863.  
  8864.  
  8865.  
  8866.              9. REXX User File Interface                               158
  8867.  
  8868.                                          usr.expdemote is set to "Y".
  8869.  
  8870.               xp_date       date         The date by which the user's
  8871.                                          account will expire. This value
  8872.                                          will only be checked if
  8873.                                          usr.expdate is set to "Y".
  8874.  
  8875.               xp_mins       long         The number of on-line minutes
  8876.                                          remaining in the user's sub-
  8877.                                          scription. This field is only
  8878.                                          debited if usr.expmins is set
  8879.                                          to "Y".
  8880.  
  8881.               expdate       bool         If this is set to "Y", the ex-
  8882.                                          pire-by-date feature is acti-
  8883.                                          vated.
  8884.  
  8885.               expmins       bool         If this is set to "Y", the ex-
  8886.                                          pire-by-time feature is acti-
  8887.                                          vated.
  8888.  
  8889.               expdemote     bool         If this is set to "Y", the user
  8890.                                          is demoted to the privilege
  8891.                                          level specified by the xp_priv
  8892.                                          field when the subscription ex-
  8893.                                          pires.
  8894.  
  8895.               expaxe        bool         If this is set to "Y", Maximus
  8896.                                          will hang up and purge the
  8897.                                          user's user record when the
  8898.                                          subscription expires.
  8899.  
  8900.               ludate        date         The beginning time of the
  8901.                                          user's last call.
  8902.  
  8903.               xkeys         keys         The keys held by the user.
  8904.  
  8905.               lang          char         The user's current language
  8906.                                          number, with 0 being the first
  8907.                                          language declared in the lan-
  8908.                                          guage control file, 1 being the
  8909.                                          second language, and so on.
  8910.  
  8911.               def_proto     char         This represents the user's de-
  8912.                                          fault protocol. A value of -1
  8913.                                          indicates no default protocol;
  8914.                                          -2 is Xmodem; -3 is Ymodem; -4
  8915.                                          is Xmodem-1K; -5 is SEAlink; -6
  8916.                                          is Zmodem; and -7 is Ymodem-G.
  8917.  
  8918.                                          A value of 0 or greater repre-
  8919.                                          sents an external protocol.
  8920.  
  8921.  
  8922.  
  8923.              9. REXX User File Interface                               159
  8924.  
  8925.               up            long         The total number of kilobytes
  8926.                                          uploaded by the user.
  8927.  
  8928.               down          long         The total number of kilobytes
  8929.                                          downloaded by the user.
  8930.  
  8931.               downtoday     long         The number of kilobytes down-
  8932.                                          loaded by the user today.
  8933.  
  8934.               msg           string       The user's current message
  8935.                                          area.
  8936.  
  8937.               files         string       The user's current file area.
  8938.  
  8939.               compress      char         The user's default compression
  8940.                                          format. A value of -1 indicates
  8941.                                          no default compressor.
  8942.  
  8943.               dataphone     string[18]   The user's business/data phone
  8944.                                          number.
  8945.  
  8946.               dob_year      int          The year in which the user was
  8947.                                          born.
  8948.  
  8949.               dob_month     int          The month in which the user was
  8950.                                          born.
  8951.  
  8952.               dob_day       int          The day of month in which the
  8953.                                          user was born.
  8954.  
  8955.               msgs_posted   long         The number of messages that the
  8956.                                          user has posted.
  8957.  
  8958.               msgs_read     long         The number of messages that the
  8959.                                          user has read.
  8960.  
  8961.               sex           int          The user's gender. (0 = un-
  8962.                                          known; 1 = male; 2 = female.)
  8963.  
  8964.               date_1stcall  date         The date of the user's first
  8965.                                          call.
  8966.  
  8967.               date_pwd_chg  date         The date of the user's last
  8968.                                          password change.
  8969.  
  8970.               nup           long         The number of files that the
  8971.                                          user has uploaded.
  8972.  
  8973.               ndown         long         The number of files that the
  8974.                                          user has downloaded.
  8975.  
  8976.               ndowntoday    long         The number of files that the
  8977.  
  8978.  
  8979.  
  8980.              9. REXX User File Interface                               160
  8981.  
  8982.                                          user has downloaded today.
  8983.  
  8984.               time_added    int          The time credits given to the
  8985.                                          user for the current day.
  8986.  
  8987.               point_credit  int          The number of points that have
  8988.                                          been credited to the user.
  8989.  
  8990.               point_debit   int          The number of points that have
  8991.                                          been debited from the user.
  8992.  
  8993.  
  8994.  
  8995.  
  8996.  
  8997.  
  8998.  
  8999.  
  9000.                                         10. Introduction to MEX Programming
  9001.  
  9002.  
  9003.              10.1. About MEX
  9004.  
  9005.              The Maximus Extension Language (MEX) is an advanced program-
  9006.              ming language designed to interface with the Maximus bulletin
  9007.              board system. MEX is a true programming language that pro-
  9008.              vides support for many advanced language features, including
  9009.              functions, dynamic strings and arrays.
  9010.  
  9011.              MEX can be used to add user-defined features and extend the
  9012.              functionality of a standard Maximus system. For example, MEX
  9013.              can be used to implement a full-screen chat program, a call-
  9014.              back verifier, or to implement a user-specific database using
  9015.              standard file I/O function calls.
  9016.  
  9017.              MEX was designed to overcome limitations in MECCA, which was
  9018.              the original Maximus extension language. MECCA was primarily
  9019.              intended to handle simplistic screen formatting and graphics,
  9020.              but it could also handle very simple forms of flow control
  9021.              and menus.
  9022.  
  9023.              Although MECCA is still supported, MEX is the extension lan-
  9024.              guage of choice for many advanced tasks. As an example of
  9025.              MEX's power, parts of the standard Maximus distribution have
  9026.              been rewritten in MEX, including the file and message area
  9027.              headers, the Change Menu, and more.
  9028.  
  9029.              MEX can interface to internal Maximus routines to obtain in-
  9030.              formation about the current user, to display screen output,
  9031.              or to perform repetition and flow control. In fact, MEX pro-
  9032.              grams can accomplish almost anything that can be done in a
  9033.              general-purpose programming language such as C or Pascal.
  9034.  
  9035.              However, all of this power does not mean that MEX is hard to
  9036.              use. The MEX language incorporates the best features from the
  9037.              C, BASIC and Pascal languages, including time-saving features
  9038.              such as dynamic strings, pass-by-reference parameters, and
  9039.              structures.
  9040.  
  9041.  
  9042.              10.2. MEX Road Map
  9043.  
  9044.              The rest of this section introduces a simple MEX program, de-
  9045.              scribes how to compile MEX programs, and describes how to run
  9046.              MEX programs from Maximus.
  9047.  
  9048.              To find more information about MEX:
  9049.  
  9050.  
  9051.  
  9052.              10. Introduction to MEX Programming                       162
  9053.  
  9054.              *  For general information on MEX programming and language
  9055.                 features, please see section 11.
  9056.  
  9057.              *  For information on the MEX run-time library, please see
  9058.                 section 15.
  9059.  
  9060.              *  For reference information on the MEX language itself, in-
  9061.                 cluding the language grammar, please see section 16.
  9062.  
  9063.  
  9064.              10.3. Creating a Sample MEX Program
  9065.  
  9066.              Like MECCA, MEX is a compiled language. This means that the
  9067.              description of what the program does, otherwise known as the
  9068.              source file, must be processed by the MEX compiler before the
  9069.              program can be run. Source files always have an extension of
  9070.              .mex.
  9071.  
  9072.              The source for a MEX program is simply an ASCII text file. An
  9073.              external editor, such as the DOS edit.com or the OS/2 e.exe,
  9074.              is used to create and edit a MEX source file.
  9075.  
  9076.              The best way to start programming in MEX is to write a sample
  9077.              program. To do this, start up a text editor (such as one of
  9078.              the two programs mentioned above). Then enter the following
  9079.              lines, using punctuation and spaces exactly as shown below:
  9080.  
  9081.                 #include <max.mh>
  9082.  
  9083.                 // This is a hello world program.
  9084.  
  9085.                 int main()
  9086.                 {
  9087.                   print("Hello, world\n");
  9088.                   return 0;
  9089.                 }
  9090.  
  9091.              After the text has been entered, double-check each line to
  9092.              ensure that it appears just like given above.
  9093.  
  9094.              When run, this program will simply print "Hello, world" and
  9095.              return to Maximus. However, before trying to compile and run
  9096.              this program, it will help to become familiar with the basic
  9097.              elements of the MEX language:
  9098.  
  9099.                 #include <max.mh>
  9100.  
  9101.              This line, "#include <max.mh>", must be present in all MEX
  9102.              programs. This line instructs the MEX compiler to read in a
  9103.              .mh file (a MEX header) that tells it how to interface with
  9104.              Maximus.
  9105.  
  9106.  
  9107.  
  9108.              10. Introduction to MEX Programming                       163
  9109.  
  9110.              Without the max.mh file, MEX would not know how to display
  9111.              output to the user, how to access information in the user re-
  9112.              cord, or how to perform many other operations.
  9113.  
  9114.              Unless otherwise noted, max.mh is the only header file that
  9115.              needs to be included in most MEX programs.
  9116.  
  9117.                 // This is a hello world program.
  9118.  
  9119.              This line is a comment. A comment begins with two forward
  9120.              slashes, and everything on the same line, following the
  9121.              slashes, is ignored by the compiler.
  9122.  
  9123.              The MEX compiler completely ignores comments, so it is quite
  9124.              possible to write a "commentless" program. However, comments
  9125.              serve to remind the reader about how a program works, and
  9126.              they can also act as an aid to other people who try to modify
  9127.              an existing MEX program.
  9128.  
  9129.              In general, it is a good idea to place comments throughout a
  9130.              MEX program, especially in areas where the program logic is
  9131.              not self-evident.
  9132.  
  9133.                 int main()
  9134.                 {
  9135.                   (inner portion of source omitted)
  9136.                 }
  9137.  
  9138.              The structure shown above is known as a function. Functions
  9139.              are the building blocks which are used to create MEX pro-
  9140.              grams. All of the actions that a MEX program performs are
  9141.              contained within functions. Only a brief description of func-
  9142.              tions will be given here, but a detailed discussion of func-
  9143.              tions can be found in section 11.
  9144.  
  9145.              The first line of the function, "int main()", tells the MEX
  9146.              compiler to create a function called "main". All MEX programs
  9147.              must have a main function. When a MEX program receives con-
  9148.              trol from Maximus, the program will always start running at
  9149.              the main function.
  9150.  
  9151.              The braces, "{" and "}", serve as bounds for the main func-
  9152.              tion. Everything that is part of the main function must be
  9153.              inside the braces.
  9154.  
  9155.                 print("Hello, world\n");
  9156.  
  9157.              This statement is the "meat" of our simple program, since it
  9158.              instructs Maximus to perform a specific action. This line is
  9159.              a function call, which consists of a function name, followed
  9160.              by a pair of parentheses which contain the function argu-
  9161.              ments.
  9162.  
  9163.  
  9164.  
  9165.              10. Introduction to MEX Programming                       164
  9166.  
  9167.              In this case, the function name is print. The print function
  9168.              is used to send output to the screen.
  9169.  
  9170.              The function arguments are "Hello, world\n". The print func-
  9171.              tion will take the provided arguments and display them on the
  9172.              screen. (The "\n" is a newline escape sequence, as will be
  9173.              explained later in more detail.)
  9174.  
  9175.              In short, while the function name tells Maximus what to do,
  9176.              the function arguments tell Maximus how to do it.
  9177.  
  9178.              Several other things are noteworthy about this function call:
  9179.  
  9180.              *  The line ends with a semicolon. In MEX, all statements must
  9181.                 end with a semicolon. In most places, the MEX compiler ig-
  9182.                 nores whitespace (such as spaces, tabs, and ends of lines),
  9183.                 so it uses the semicolon to mark the end of a statement.
  9184.  
  9185.              *  Notice that the function argument, "Hello, world\n", is en-
  9186.                 closed in double quotes. In MEX, this is known as a string.
  9187.                 Strings consist of zero or more letters, numbers, or punc-
  9188.                 tuation marks that are surrounded by a pair of double
  9189.                 quotes. Strings are used for storing, manipulating, and
  9190.                 displaying words and other types of textual information.
  9191.  
  9192.              *  In the example above, the print function was only called
  9193.                 with one argument. Some functions only accept a fixed num-
  9194.                 ber of arguments, but in the case of print, it can accept
  9195.                 as many arguments as desired.
  9196.  
  9197.                 To pass more than one argument to a function, simply add a
  9198.                 comma-delimited list of arguments within the parentheses.
  9199.                 For example, to print the words "Alex", "Betty" and
  9200.                 "Chuck", the following line could be used:
  9201.  
  9202.                   print("Alex ", "Betty ", "Chuck ");
  9203.  
  9204.                 In addition, some functions do not accept any arguments.
  9205.                 Even in these cases, the parentheses must still be present,
  9206.                 since they denote that a function call should be made. For
  9207.                 example, given a function called foo that accepted no argu-
  9208.                 ments, it could be called like this:
  9209.  
  9210.                   foo();
  9211.  
  9212.              *  In the function argument, the last two characters, "\n,"
  9213.                 are known as an escape sequence. When the MEX compiler sees
  9214.                 a backslash followed by the letter n, it recognizes this as
  9215.                 the newline escape sequence. This escape sequence then gets
  9216.                 translated to a linefeed, which causes the cursor to skip
  9217.                 down to the next line after the string is displayed.
  9218.  
  9219.  
  9220.  
  9221.              10. Introduction to MEX Programming                       165
  9222.  
  9223.                 In short, every time MEX sees a "\n" enclosed in double
  9224.                 quotes, the "\n" causes the cursor to be sent to the begin-
  9225.                 ning of the next line.
  9226.  
  9227.                 For example, if our sample program contained the following
  9228.                 line:
  9229.  
  9230.                   print("This is a\ntest of the\n\noutput text.\n");
  9231.  
  9232.                 then the output would look like this:
  9233.  
  9234.                   This is a
  9235.                   test of the
  9236.  
  9237.                   output text.
  9238.  
  9239.                 While other escape sequences are also supported, only the
  9240.                 newline escape sequence is important for now.
  9241.  
  9242.              We finish our analysis of the sample program by examining the
  9243.              last line in the main function:
  9244.  
  9245.                 return 0;
  9246.  
  9247.              This line is a return statement. This statement indicates to
  9248.              Maximus that the MEX program completed successfully. This
  9249.              normally appears as the last line in the main function. (The
  9250.              return statement has other uses which will be discussed
  9251.              later; but for simple, single-function programs, only one re-
  9252.              turn statement is necessary.)
  9253.  
  9254.              This completes our analysis of the sample MEX program. See
  9255.              the following sections for information on compiling and exe-
  9256.              cuting MEX programs under Maximus.
  9257.  
  9258.  
  9259.              10.4. Compiling MEX Programs
  9260.  
  9261.              The main purpose of the MEX compiler, mex.exe, is to read in
  9262.              a source .mex file and compile it into a .vm file. This .vm
  9263.              file can be read and executed by Maximus. The compilation
  9264.              converts the MEX source file into a form that can be executed
  9265.              while a user is on-line.
  9266.  
  9267.              The secondary purpose of the MEX compiler is to check the
  9268.              program source for errors. If the compiler detects an error
  9269.              while compiling your source, it will print an error message
  9270.              and abort the compilation. A text editor must then be used to
  9271.              edit the source file and correct the error.
  9272.  
  9273.              Assuming that you called your file test.mex, simply type the
  9274.              following to compile the program:
  9275.  
  9276.  
  9277.  
  9278.              10. Introduction to MEX Programming                       166
  9279.  
  9280.                 mex test.mex
  9281.  
  9282.              The compiler will then process the source file. If the source
  9283.              file is incorrect, the compiler will display error messages
  9284.              and abort the compilation. If this happens, ensure that the
  9285.              source file matches the example given in the section above.
  9286.              (The line numbers given in the warning messages can be used
  9287.              to determine the approximate location of the error.)
  9288.  
  9289.  
  9290.              10.5. Running MEX Programs
  9291.  
  9292.              Once a MEX program has been compiled, it can be executed by
  9293.              Maximus.
  9294.  
  9295.              There are three primary ways to invoke a MEX program from
  9296.              Maximus: from a menu option, from a .bbs or .mec file, or
  9297.              from a File or Uses statement in max.ctl:
  9298.  
  9299.  
  9300.              10.5.1. Running MEX Programs from Menu Options
  9301.  
  9302.              The easiest way to add a new MEX program to the system is to
  9303.              give it its own menu option. To add a menu option, a line
  9304.              similar to the following can be added to one of the menu
  9305.              definitions in menus.ctl.
  9306.  
  9307.              For example, the following line can be added to the defini-
  9308.              tion for "Menu Main" to run the MEX program that was created
  9309.              in the previous section:
  9310.  
  9311.                 MEX     m\test                  Normal   "Test"
  9312.  
  9313.              This line instructs Maximus to execute a program called
  9314.              m\test. Maximus will assume that the file is relative to the
  9315.              main Maximus directory, so if you installed Maximus in
  9316.              c:\max, it will expect to find the file in the c:\max\m di-
  9317.              rectory.
  9318.  
  9319.              After making changes to menus.ctl, the Maximus control files
  9320.              should also be recompiled with SILT.
  9321.  
  9322.              Maximus reads in the compiled source file (as generated by
  9323.              the MEX compiler), so it will actually be looking for a file
  9324.              called c:\max\m\test.vm. If the file is not found, an appro-
  9325.              priate error message will be displayed (and also placed in
  9326.              the system log).
  9327.  
  9328.              If everything went well, upon pressing the "T" key at the
  9329.              main menu, the output of the "Hello world" program should ap-
  9330.              pear on the screen.
  9331.  
  9332.  
  9333.  
  9334.              10. Introduction to MEX Programming                       167
  9335.  
  9336.              For more information on the format of menu options, please
  9337.              see section 18.8.
  9338.  
  9339.  
  9340.              10.5.2. Running MEX Programs from .MEC Files
  9341.  
  9342.              If desired, MEX programs can also be run directly from .mec
  9343.              or .bbs files. The [mex] MECCA token tells Maximus to run a
  9344.              MEX program:
  9345.  
  9346.              For example, these lines could be added to welcome.mec:
  9347.  
  9348.                 [mex]m\test
  9349.                 [pause]
  9350.  
  9351.              After recompiling the welcome.mec file with MECCA, the
  9352.              c:\max\m\test.vm program will be run every time a user logs
  9353.              on, in addition to displaying the rest of the normal welcome
  9354.              screen.
  9355.  
  9356.  
  9357.              10.5.3. Running MEX Programs from MAX.CTL
  9358.  
  9359.              In many of the Maximus control files, numerous keywords allow
  9360.              .bbs filenames to be specified. Maximus allows a MEX program
  9361.              to be substituted for a .bbs file in any of these places.
  9362.  
  9363.              To indicate to Maximus that it is to run a MEX program in-
  9364.              stead of a .bbs file, simply add a colon (":") to the begin-
  9365.              ning of the filename. For example, to completely replace the
  9366.              \max\misc\logo.bbs file with a MEX program, the Uses Logo
  9367.              statement in max.ctl can be modified to read as follows:
  9368.  
  9369.                 Uses Logo   :M\Test
  9370.  
  9371.              In this line were used, instead of displaying the standard
  9372.              \max\misc\logo.bbs file, Maximus would instead run the
  9373.              \max\m\test.vm program.
  9374.  
  9375.              This technique can also be applied to any other part of the
  9376.              system that requests a .bbs filename. For example, even
  9377.              though the MEX menu option can be used to run MEX programs
  9378.              directly, we can also use the Display_File menu option to
  9379.              display a MEX program, even though it is normally used to
  9380.              display .bbs files:
  9381.  
  9382.                 Display_File   :M\Test               Normal   "Test"
  9383.  
  9384.  
  9385.  
  9386.  
  9387.  
  9388.  
  9389.  
  9390.  
  9391.                                                   11. MEX Language Tutorial
  9392.  
  9393.              This section is an introduction to programming in MEX. No
  9394.              prior programming experience is assumed, although familiarity
  9395.              with other programming languages will help in some areas.
  9396.              While this section tries to teach some basic programming
  9397.              principles, it is not a substitute for a general text on pro-
  9398.              gramming methodology.
  9399.  
  9400.              Before reading this section, new programmers should first
  9401.              read and try out the "Hello world" program from the introduc-
  9402.              tion..
  9403.  
  9404.              Those who are already familiar with C or Pascal should read
  9405.              section 12. That section provides a brief overview of the
  9406.              differences between MEX and each of the other two languages.
  9407.              However, material in this section will also be helpful in
  9408.              demonstrating basic language principles.
  9409.  
  9410.  
  9411.              11.1. Program Development Cycle
  9412.  
  9413.              Like many things, designing a MEX program is an iterative
  9414.              task. Seldom do developers write a program correctly on the
  9415.              first attempt; this section is an introduction to the devel-
  9416.              opment cycle of a typical computer program.
  9417.  
  9418.              The first step in designing a computer program is to deter-
  9419.              mine the end goal of the program. What must the program do?
  9420.              What are its inputs? What are its outputs?
  9421.  
  9422.              These three questions must be answered before any further
  9423.              steps can be taken in program design. Without a clear idea of
  9424.              what a program is supposed to accomplish, proceeding to the
  9425.              design and implementation stages all but guarantees a poorly-
  9426.              designed program in the long run.
  9427.  
  9428.              After the program's inputs and outputs have been determined,
  9429.              the next step is to decompose the program's operations into
  9430.              functional units. This process is described in more detail in
  9431.              section 11.2.1 (below), but in essence, it involves breaking
  9432.              a large problem into many smaller subproblems.
  9433.  
  9434.              The next step is the implementation stage. Here, you must en-
  9435.              ter the program source code (or a portion thereof) into the
  9436.              computer. The program source code now takes the form of an
  9437.              ASCII source file with a .mex extension.
  9438.  
  9439.  
  9440.  
  9441.              11. MEX Language Tutorial                                 170
  9442.  
  9443.              Now, the MEX compiler is invoked to compile the program
  9444.              source. If any compilation errors occur, you must go back to
  9445.              the previous step and re-edit the program.
  9446.  
  9447.              Additionally, a compile-time error might alert you to a prob-
  9448.              lem with the program design. In this case, you must return to
  9449.              the design stage and modify the program specification.
  9450.  
  9451.              Next, the compiled MEX program is run from within Maximus.
  9452.              Even if the program compiles correctly, there still may be
  9453.              numerous functional errors in the program. If problems are
  9454.              observed, you must return to a previous stage, either to re-
  9455.              edit the program source, or to re-design the portion of the
  9456.              program that is causing the problem.
  9457.  
  9458.              In theory, if a program is designed correctly the first time,
  9459.              very few design changes will be required in the later devel-
  9460.              opment stages. However, as a program grows in size, it be-
  9461.              comes much more difficult to design the program in sufficient
  9462.              detail to ensure that all of the program components will in-
  9463.              teroperate correctly without any design revision.
  9464.  
  9465.              In addition, other factors may necessitate a design change,
  9466.              such users requesting additional features to be added to your
  9467.              program.
  9468.  
  9469.              This entire development cycle is often referred to as the
  9470.              "waterfall effect." Problems noted in the implementation
  9471.              stage may require a return to the design stage; problems in
  9472.              the compilation stage may require a return to the implementa-
  9473.              tion or design stage; problems in the execution stage may re-
  9474.              quire a return to any of the preceding stages.
  9475.  
  9476.              In addition, the impact of "feature requests" should not be
  9477.              underestimated. A common sentiment among programmers is that
  9478.              no one else except themselves will use a program, so why
  9479.              bother to design it or comment it properly? Unfortunately,
  9480.              these types of programs all too often end up being distrib-
  9481.              uted and used by others, so it usually pays to design and im-
  9482.              plement a program correctly the first time.
  9483.  
  9484.              For programs with a large base of installed users, the pro-
  9485.              gram development cycle never stops. Small changes are always
  9486.              being made to the program design; small tweaks are always be-
  9487.              ing made to the program source code; and minor problems are
  9488.              always being found during program execution.
  9489.  
  9490.              Familiarizing yourself with the program development cycle is
  9491.              the best way to ensure success when developing a program, no
  9492.              matter how large or how small.
  9493.  
  9494.  
  9495.  
  9496.              11. MEX Language Tutorial                                 171
  9497.  
  9498.              11.2. Elements of a MEX Program
  9499.  
  9500.              A standard MEX program consists of two main components: a set
  9501.              of instructions that tell the computer what to do, and the
  9502.              information on which those instructions operate.
  9503.  
  9504.              The set of instructions is often referred to as code, while
  9505.              the information on which it operates is often referred to as
  9506.              data.
  9507.  
  9508.  
  9509.              11.2.1. About Code
  9510.  
  9511.              In MEX, the program code is implemented using functions. Al-
  9512.              though the sample program in the introduction had only one
  9513.              function, main, most MEX programs have a number of intercon-
  9514.              nected functions. Functions are building blocks that are used
  9515.              to design programs in a modular manner.
  9516.  
  9517.              For example, given a MEX program that retrieves a user's date
  9518.              of birth, the program could be broken up into a number of
  9519.              functions:
  9520.  
  9521.              *  One function could display a prompt and ask the user to en-
  9522.                 ter a line of text.
  9523.  
  9524.              *  Another function could validate the text entered to ensure
  9525.                 that it is a valid date.
  9526.  
  9527.              *  A third function could store the date information in the
  9528.                 user record.
  9529.  
  9530.              *  A fourth and final function, the main function, could tie
  9531.                 all of the above functions together by invoking them in the
  9532.                 right order.
  9533.  
  9534.              Within each function are a number of statements. These state-
  9535.              ments are the step-by-step instructions that tell the com-
  9536.              puter what to do. For example, the statements in the "date
  9537.              validation function" could do something similar to the fol-
  9538.              lowing:
  9539.  
  9540.              *  Separate the date into year, month and day components
  9541.  
  9542.              *  Check if the year is greater than 1890. If not, reject the
  9543.                 date.
  9544.  
  9545.              *  Check if the month number is greater than 0 and less than
  9546.                 13. If not, reject the date
  9547.  
  9548.              *  Check if the day number is within the bounds for the indi-
  9549.                 cated month. (1 to 31, 1 to 30, 1 to 28, and so on)
  9550.  
  9551.  
  9552.  
  9553.              11. MEX Language Tutorial                                 172
  9554.  
  9555.              By breaking down the major components of a program into func-
  9556.              tions, and then by breaking down each function into a se-
  9557.              quence of statements, programs can be written to solve com-
  9558.              plex everyday problems.
  9559.  
  9560.  
  9561.              11.2.2. About Data
  9562.  
  9563.              Program data consists of constants and variables. Like the
  9564.              name implies, constants never change. Given an expression
  9565.              such as "2 + 2", the number "2" is a constant.
  9566.  
  9567.              Variables, on the other hand, can change while your program
  9568.              is being run. Variables must be given names, as in conven-
  9569.              tional mathematics. For example, given an expression such as
  9570.              "i + 2," the symbol i is a variable. Depending on the value
  9571.              of i, the expression itself can have different values. For
  9572.              example, if i has a value of 6, the value of the expression
  9573.              "i + 2" is 8.
  9574.  
  9575.              In MEX, a variable also has a type. The type of a variable
  9576.              indicates the kind of information that the variable is al-
  9577.              lowed to hold. Table 11.1 lists some of the basic data types
  9578.              supported by MEX:
  9579.  
  9580.              Table 11.1 MEX Data Types
  9581.  
  9582.               Type    Description
  9583.  
  9584.               char    Variables of this type can hold a single charac-
  9585.                       ter, including letters, numbers, digits, punctua-
  9586.                       tion, and control characters. Variables of the
  9587.                       this type can also be used to store very small
  9588.                       numbers in the range of 0 to 255. Examples of
  9589.                       characters are `a,' `6,' and `:'. Characters are
  9590.                       described in more detail in a later section.
  9591.  
  9592.               int     An int can hold numbers in the range -32768 to
  9593.                       32767. This is an "integer" data type, meaning
  9594.                       that it can only hold whole numbers, both positive
  9595.                       and negative. This means that numbers that contain
  9596.                       a fractional component, such as 8.6 and -4.3, are
  9597.                       not allowed.
  9598.  
  9599.               long    A long can hold numbers in the range -2147483648
  9600.                       to 2147483647. This is an "integer" data type,
  9601.                       meaning that it can only hold whole numbers, both
  9602.                       positive and negative. This means that numbers
  9603.                       that contain a fractional component, such as 8.6
  9604.                       and -4.3, are not allowed.
  9605.  
  9606.               string  This is a "dynamic string" data type. Strings are
  9607.                       commonly used for many word or text-oriented ap-
  9608.  
  9609.  
  9610.  
  9611.              11. MEX Language Tutorial                                 173
  9612.  
  9613.                       plications, such as printing output to the screen,
  9614.                       reading a sequence of keystrokes from the key-
  9615.                       board, or any other task which requires characters
  9616.                       to be "grouped."
  9617.  
  9618.                       Strings are dynamic in nature, meaning that they
  9619.                       grow and shrink along with their contents. Conse-
  9620.                       quently, no "maximum length" need be set when de-
  9621.                       claring a string.
  9622.  
  9623.                       Examples of dynamic strings are "Maximus" and
  9624.                       "Alexander the Great."
  9625.  
  9626.                       Strings are described in more detail in a later
  9627.                       section.
  9628.  
  9629.               struct  A structure is an aggregate, user-defined data
  9630.                       type that contains multiple objects of other
  9631.                       types. For example, a structure could hold an in-
  9632.                       teger, a character and a string. Structures will
  9633.                       be discussed in more detail in a later section.
  9634.  
  9635.               array   An array is an aggregate, user-defined data type
  9636.                       that contains multiple objects of the same data
  9637.                       type. For example, an array could contain 500 dis-
  9638.                       tinct integers.
  9639.  
  9640.               void    This is a special data type that is normally only
  9641.                       used for functions that do not return values. The
  9642.                       void data type cannot hold a value and cannot be
  9643.                       used in calculations. This type is discussed in
  9644.                       more detail in a later section.
  9645.  
  9646.  
  9647.  
  9648.              The three integral types described above, char, int and long,
  9649.              come in both signed and unsigned versions. A signed type can
  9650.              represent a negative number, whereas an unsigned type cannot.
  9651.              (However, an unsigned type can store numbers twice as large
  9652.              as a signed type.)
  9653.  
  9654.              The modifiers signed and unsigned can be inserted in front of
  9655.              one of the three integral type names to specify a signed or
  9656.              an unsigned type.
  9657.  
  9658.              The char type is unsigned by default, whereas int and long
  9659.              are both signed by default.
  9660.  
  9661.              For example, MEX supports the signed char type (with a range
  9662.              of -128 to 127), the unsigned int type (with a range of 0 to
  9663.              65536) and the unsigned long type (with a range of 0 to
  9664.              4294967296).
  9665.  
  9666.  
  9667.  
  9668.              11. MEX Language Tutorial                                 174
  9669.  
  9670.  
  9671.  
  9672.  
  9673.              11.3. Variable Declarations
  9674.  
  9675.              All MEX programs must declare variables before they can be
  9676.              used. The variable declaration tells the compiler two things:
  9677.              the name of the variable, and the type of information that
  9678.              the variable will be used to store.
  9679.  
  9680.              In a MEX program, variables can be declared in two different
  9681.              places:
  9682.  
  9683.              *  In a block at the top of the .mex source file. Variables
  9684.                 declared here are known as global variables. Global vari-
  9685.                 ables are accessible to all of the functions in a program,
  9686.                 and these variables maintain their value throughout the
  9687.                 execution of the entire program.
  9688.  
  9689.              *  In a block at the top of each function. Variables declared
  9690.                 here are known as local variables. Local variables are only
  9691.                 accessible within the function in which they are declared.
  9692.                 These variables lose their values as soon as the containing
  9693.                 function finishes executing.
  9694.  
  9695.              A variable block simply denotes an area of the source code
  9696.              that contains one or more variable declarations. There is no
  9697.              explicit keyword to tell the MEX compiler that it is process-
  9698.              ing a variable block or that variables are being declared;
  9699.              this is detected by context alone. Variables can be declared
  9700.              at the top of the source file, and just after the opening
  9701.              brace ("{") of functions.
  9702.  
  9703.              Note to advanced programmers: variables can also be placed at
  9704.              the beginning of any basic block in a function, and at other
  9705.              top-level points in the source file (outside of functions).
  9706.              However, this capability should only be used when absolutely
  9707.              necessary.
  9708.  
  9709.              A variable declaration block looks like this:
  9710.  
  9711.                 int: i, j, k;
  9712.  
  9713.              The word int is the variable type. (In declarations, every-
  9714.              thing to the left of the colon (":") is treated as the vari-
  9715.              able type.)
  9716.  
  9717.              The comma-delimited list that follows the type, "i, j, k," is
  9718.              the list of variables to declare.
  9719.  
  9720.              The variable declaration ends with a semicolon (";"). This
  9721.              semicolon tells the compiler where the declaration ends.
  9722.  
  9723.  
  9724.  
  9725.              11. MEX Language Tutorial                                 175
  9726.  
  9727.              For the most part, variable names can be assigned arbitrar-
  9728.              ily. However, a few restrictions are imposed:
  9729.  
  9730.              *  The name must be from 1 to 32 characters long.
  9731.  
  9732.              *  The name is case-sensitive. This means that "delta,"
  9733.                 "Delta," "DELTA," and "DeLtA" refer to four distinct ob-
  9734.                 jects.
  9735.  
  9736.              *  Names can include letters and underscores. Names can also
  9737.                 include digits, except in the first character of the name.
  9738.                 (This means that "top10" is a valid name, whereas "7up" is
  9739.                 not.)
  9740.  
  9741.              In the example above, three integers were created, with names
  9742.              i, j and k. Of course, variables of different types can also
  9743.              be declared within one block. The example below shows how to
  9744.              declare variables of different types within a declaration
  9745.              block:
  9746.  
  9747.                 char: c;
  9748.                 string: str;
  9749.                 int: i;
  9750.                 int: j;
  9751.  
  9752.              In the declaration above, a character c is created, in addi-
  9753.              tion to a string str and integers i and j. Notice that a
  9754.              semicolon follows each declaration.
  9755.  
  9756.              A comma-delimited list could have also been used to write an
  9757.              equivalent declaration block:
  9758.  
  9759.                 char: c;
  9760.                 string: str;
  9761.                 int: i, j;
  9762.  
  9763.              As can be seen above, variables of the same type can be de-
  9764.              clared in a comma-delimited list, as well as in separate dec-
  9765.              larations, with no change in functionality.
  9766.  
  9767.              All integral variables are automatically initialized to 0
  9768.              when they are declared. All string variables are initialized
  9769.              to the null string ("").
  9770.  
  9771.  
  9772.              11.3.1. Character Variables
  9773.  
  9774.              Both the char and string data types are used for storing dis-
  9775.              playable information. However, characters and strings are
  9776.              used for quite distinct purposes.
  9777.  
  9778.              A char is normally used when only one letter, number, punc-
  9779.              tuation symbol or control character needs to be stored. In
  9780.  
  9781.  
  9782.  
  9783.              11. MEX Language Tutorial                                 176
  9784.  
  9785.              addition, a char can store any integer number that is in the
  9786.              range 0 to 255. Hence, chars are also useful for storing very
  9787.              small numbers.
  9788.  
  9789.              To assign a value to a variable of type char, simply enclose
  9790.              the letter, number or punctuation mark in single quotes. For
  9791.              example:
  9792.  
  9793.                 char: c;
  9794.  
  9795.                 c := 'q';        // c holds the letter q
  9796.                   or
  9797.                 c := ':';        // c holds a colon
  9798.  
  9799.              This approach is adequate for assigning most types of charac-
  9800.              ter constants. However, some character values cannot be con-
  9801.              veniently entered in this approach. For example, how does one
  9802.              enter a newline character, or for that matter, how does one
  9803.              enter a character that contains a single quote?
  9804.  
  9805.              The answer lies in escape characters. Within character con-
  9806.              stants (and also within strings), the backslash is used as an
  9807.              escape character. Whenever the compiler recognizes an escape
  9808.              character in a character or string constant, it also reads
  9809.              the immediately-following character and treats the two as a
  9810.              pair.
  9811.  
  9812.              By using two-character escape sequences, you can easily place
  9813.              non-printable and special characters in the source file.
  9814.              Table 11.2 lists the escape characters supported by MEX:
  9815.  
  9816.              Table 11.2 MEX Escape Characters
  9817.  
  9818.               Escape    Name       ASCII  Description
  9819.               character            code
  9820.  
  9821.               \n        Newline    10     As seen in the sample MEX pro-
  9822.                                           gram in the introduction, this
  9823.                                           character sends the cursor down
  9824.                                           one line and moves it to the
  9825.                                           left-hand side of the screen.
  9826.               \r        Carriage   13     A carriage return moves the
  9827.                         return            cursor to the beginning of the
  9828.                                           current line.
  9829.               \a        BEL        7      The BEL character sends an
  9830.                                           audible beep to the user. (When
  9831.                                           displayed using print, this is
  9832.                                           normally not heard on the local
  9833.                                           console.)
  9834.               \b        Backspace  8      The backspace character moves
  9835.                                           the cursor back by one column.
  9836.               \f        Formfeed   12     The formfeed character clears
  9837.                                           the screen.
  9838.  
  9839.  
  9840.  
  9841.              11. MEX Language Tutorial                                 177
  9842.  
  9843.               \t        Tab        9      The tab character sends the
  9844.                                           cursor to the next horizontal
  9845.                                           tab stop.
  9846.               \'        Single     39     A single quote character (').
  9847.                         Quote
  9848.               \"        Double     34     A double quote character (").
  9849.                         Quote
  9850.               \\        Backslash  92     A backslash character (\).
  9851.  
  9852.  
  9853.  
  9854.              11.3.2. String Variables
  9855.  
  9856.              Strings are normally used when a large number of characters
  9857.              need to be manipulated as a single block, or when parts of a
  9858.              block of characters need to be manipulated independently.
  9859.  
  9860.              Strings can be assigned just like any other variables:
  9861.  
  9862.                 string: s;
  9863.  
  9864.                 s := "Julius Caesar";
  9865.  
  9866.              After this code is run, the variable s will contain "Julius
  9867.              Caesar." To modify the string at a later point in the pro-
  9868.              gram, only reassigning the string is necessary, as shown be-
  9869.              low:
  9870.  
  9871.                 #include <max.mh>
  9872.  
  9873.                 int main()
  9874.                 {
  9875.                   string: s;
  9876.  
  9877.                   s := "Napoleon";
  9878.  
  9879.                   // ... perform conquests here ...
  9880.  
  9881.                   s := "King Henry IV";
  9882.                   return 0;
  9883.                 }
  9884.  
  9885.              In the above program segment, the assignment of strings of
  9886.              varying length to s is automatically managed by the MEX run-
  9887.              time environment. No explicit "maximum length" need be speci-
  9888.              fied when declaring the variables, regardless of the size of
  9889.              the string.
  9890.  
  9891.              Strings can include any of the escape characters described in
  9892.              the previous section.
  9893.  
  9894.              In addition, MEX allows you to manipulate parts of strings as
  9895.              characters. The "[ ]" operator can be used to extract a char-
  9896.  
  9897.  
  9898.  
  9899.              11. MEX Language Tutorial                                 178
  9900.  
  9901.              acter from a specific point in a string, or to place a new
  9902.              character into a string. The expression:
  9903.  
  9904.                 str [ idx ]
  9905.  
  9906.              instructs MEX to extract character number idx from the string
  9907.              and to convert it to a character, with an idx of 1 represent-
  9908.              ing the first character in the string.
  9909.  
  9910.              This notation can be used for both examining characters in
  9911.              strings and modifying the characters in an existing string.
  9912.              MEX will automatically expand the string and pad it with
  9913.              spaces if an expression attempts to add a character beyond
  9914.              the end of the string.
  9915.  
  9916.              For example:
  9917.  
  9918.                 #include <max.mh>
  9919.  
  9920.                 int main()
  9921.                 {
  9922.                   string: s;
  9923.                   char: c;
  9924.  
  9925.                   s := "Philistine";
  9926.                   c := s[1];        // c is now 'P'
  9927.                   s[3] := c;        // s is now "PhPlistine"
  9928.  
  9929.                   // Now expand string by writing beyond end.
  9930.  
  9931.                   s[13] := 'o';     // s is now "PhPlistine  o"
  9932.                   print(s);
  9933.                   return 0;
  9934.                 }
  9935.  
  9936.              11.4. Variable Scope
  9937.  
  9938.              A variable's scope is defined as the region of the source
  9939.              code which is capable of accessing or modifying that vari-
  9940.              able. The MEX rules for scoping are derived from the C lan-
  9941.              guage (which was in turn derived from Algol 68).
  9942.  
  9943.              In MEX, two simple scoping rules are applied:
  9944.  
  9945.              *  The scope of global variables begins at the point in the
  9946.                 source file where they are declared. The scope of the vari-
  9947.                 able extends to the end of the file. A variable which is
  9948.                 declared as global can be used by any function in the en-
  9949.                 tire program, and the variable's contents are preserved
  9950.                 across function calls. Variables can be declared globally
  9951.                 by simply placing the declaration at the top of the file,
  9952.                 outside of any function body.
  9953.  
  9954.  
  9955.  
  9956.              11. MEX Language Tutorial                                 179
  9957.  
  9958.              *  The scope of a local variable begins at the opening brace
  9959.                 ("{") of the block in which it is declared. The scope ex-
  9960.                 tends over all nested blocks, and it terminates at the
  9961.                 closing brace ("}") of the block in which it was declared.
  9962.                 Variables declared inside a function are said to have a lo-
  9963.                 cal scope, since they can only be accessed from within that
  9964.                 function. Variables with a local scope are automatically
  9965.                 allocated and deallocated when a function is called; hence,
  9966.                 local variables do not have their values preserved across
  9967.                 different calls of the same function.
  9968.  
  9969.  
  9970.              11.5. Preprocessor
  9971.  
  9972.              The MEX compiler includes a rudimentary preprocessor which is
  9973.              controlled by preprocessor directives. These directives in-
  9974.              struct it to perform compile-time substitutions and compari-
  9975.              sons of keywords in the source code.
  9976.  
  9977.              All preprocessor directives begin with a hash ("#") character
  9978.              at the beginning of the line.
  9979.  
  9980.              MEX supports the following preprocessor directives:
  9981.  
  9982.              #define name value
  9983.  
  9984.                 The #define directive instructs the compiler to examine the
  9985.                 source code and replace all instances of the word name with
  9986.                 the value of value. For all intents and purposes, the com-
  9987.                 piler behaves as if value had been entered in the source
  9988.                 code rather than name. All such substitutions are performed
  9989.                 before a source line is processed by the rest of the com-
  9990.                 piler.
  9991.  
  9992.                 For example, the following piece of code:
  9993.  
  9994.                 #define ASSIGN_VARIABLE myint
  9995.  
  9996.                 int: myint;
  9997.  
  9998.                 ASSIGN_VARIABLE := 3;
  9999.  
  10000.                 is equivalent to the following code in all respects:
  10001.  
  10002.                 int: myint;
  10003.  
  10004.                 myint := 3;
  10005.  
  10006.              #include <filename>
  10007.  
  10008.                 The #include directive instructs the compiler to read in
  10009.                 the header file filename and process it as if its contents
  10010.                 were placed directly within the source file being compiled.
  10011.  
  10012.  
  10013.  
  10014.              11. MEX Language Tutorial                                 180
  10015.  
  10016.                 This directive is useful for splitting up a large file into
  10017.                 multiple parts.
  10018.  
  10019.                 In the introduction, the #include directive was also used
  10020.                 to include a file called max.mh, the standard system in-
  10021.                 clude file. The max.mh file contains all of the definitions
  10022.                 required to interface your program with Maximus. While
  10023.                 these definitions could be copied into each and every MEX
  10024.                 program, it is much more convenient to put these defini-
  10025.                 tions all in one place and then #include the file from all
  10026.                 MEX programs.
  10027.  
  10028.                 The filename to be included must be placed within angle
  10029.                 brackets, as shown in the example above. MEX will first
  10030.                 look for the file in the current directory; if it cannot be
  10031.                 found there, MEX will try to find the file in the same di-
  10032.                 rectory as the .mex file that is currently being compiled.
  10033.                 Finally, MEX will attempt to find the file in the directory
  10034.                 specified by the MEX_INCLUDE environment variable.
  10035.  
  10036.  
  10037.              11.6. Calculations and Arithmetic
  10038.  
  10039.              MEX supports a wide variety of arithmetic and logical opera-
  10040.              tors which permit many different operations to be performed
  10041.              on the variables and data used by a program.
  10042.  
  10043.              After declaring a set of variables that can hold arbitrary
  10044.              values, the next thing a programmer may want to do is assign
  10045.              values to those variables.
  10046.  
  10047.              The simplest way to assign a value to a variable is to use
  10048.              the assignment operator. The assignment operator is entered
  10049.              as two separate characters: a colon followed immediately by
  10050.              an equals sign (":=").
  10051.  
  10052.              The assignment operator is similar to the "equals sign" in
  10053.              conventional mathematics; it assigns the value on the right-
  10054.              hand side of the assignment operator to the variable on the
  10055.              left-hand side.
  10056.  
  10057.              For example, after running the following program:
  10058.  
  10059.                 #include <max.mh>
  10060.  
  10061.                 int main()
  10062.                 {
  10063.                   int: i;
  10064.                   char: c;
  10065.                   long: l;
  10066.  
  10067.                   i := 4;
  10068.                   c := 'q';
  10069.  
  10070.  
  10071.  
  10072.              11. MEX Language Tutorial                                 181
  10073.  
  10074.                   l := 12345678;
  10075.  
  10076.                   return 0;
  10077.                 }
  10078.  
  10079.              the variable i will contain the number 4, c will contain the
  10080.              character 'q', and l will contain the number 12345678.
  10081.  
  10082.              One variable can also be assigned to another, as shown in the
  10083.              following program:
  10084.  
  10085.                 #include <max.mh>
  10086.  
  10087.                 int main()
  10088.                 {
  10089.                   int: i, j;
  10090.  
  10091.                   i := 3;   // i now contains 3
  10092.                   j := i;   // j now contains 3 too
  10093.  
  10094.                   return 0;
  10095.                 }
  10096.  
  10097.              In addition, many other operations can be performed on vari-
  10098.              ables. Many of the standard arithmetic operations, including
  10099.              addition, subtraction, multiplication and division, can also
  10100.              be performed on variables of types char, int and long. (Note
  10101.              that arithmetic operations cannot be performed on strings.
  10102.              However, the "+" symbol functions as a catenation operator to
  10103.              combine the contents of two strings.)
  10104.  
  10105.              MEX also supports a set of boolean logic operators, including
  10106.              "and" and "or." Lastly, MEX also supports bitwise logic op-
  10107.              erators, such as bitwise and and bitwise or.
  10108.  
  10109.              In general, an operator can be combined and used with other
  10110.              variables as follows:
  10111.  
  10112.                 <expression-left> <operator> <expression-right>
  10113.  
  10114.              <operator> is one of the arithmetic operators from the table
  10115.              below. <expression-left> and <expression-right> can be arbi-
  10116.              trary expressions made up of other operators. For an example,
  10117.              given "3 + 5," the <expression-left> would be "3", the
  10118.              <operator> would be "+," and the <expression-right> would be
  10119.              "5."
  10120.  
  10121.              Table 11.3 lists the operators supported by MEX:
  10122.  
  10123.  
  10124.  
  10125.              11. MEX Language Tutorial                                 182
  10126.  
  10127.              Table 11.3 MEX Operators
  10128.  
  10129.               Operator  Description
  10130.  
  10131.               +         Addition and catenation. This operator yields the
  10132.                         arithmetic addition of two integer operands, such
  10133.                         as an int and an int, or a long and a long.
  10134.  
  10135.                         Also, when both <expression-left> and
  10136.                         <expression-right> are strings, the + operator
  10137.                         functions as a catenation operator to combine the
  10138.                         two strings.
  10139.  
  10140.               -         Subtraction. This operator yields the arithmetic
  10141.                         difference of the right-hand operand and the
  10142.                         left-hand operand.
  10143.  
  10144.               *         Multiplication. This operator yields the arithme-
  10145.                         tic multiplication of the left-hand operand with
  10146.                         the right-hand operand.
  10147.  
  10148.               /         Division. This operator yields the arithmetic di-
  10149.                         vision of the left-hand operand by the right-hand
  10150.                         operand.
  10151.  
  10152.               %         Modulo-division. This operator yields the remain-
  10153.                         der of the left-hand operand divided by the
  10154.                         right-hand operand.
  10155.  
  10156.               =         Equality. The result of an equality comparison is
  10157.                         1 if the two compared objects contain the same
  10158.                         value, or 0 if they do not.
  10159.  
  10160.               <>        Inequality. The result of an inequality compari-
  10161.                         son is 1 if the two compared objects do not con-
  10162.                         tain the same value, and 0 if they do.
  10163.  
  10164.               <=, <,    Logical comparators. These are the less-than-or-
  10165.               >=, >     equal, less-than, greater-than-or-equal and
  10166.                         greater-than operators. All of these operators
  10167.                         yield a result of 1 if the comparison between the
  10168.                         left-hand operand and the right-hand operand is
  10169.                         true; otherwise, they yield 0.
  10170.  
  10171.               and       Logical and. The logical and operator yields a
  10172.                         result of 1 if both of its operands are non-zero;
  10173.                         otherwise, it yields 0.
  10174.  
  10175.               or        Logical or. The logical or operator yields a re-
  10176.                         sult of 1 if either (or both) of its operands are
  10177.                         non-zero; otherwise, it yields 0.
  10178.  
  10179.  
  10180.  
  10181.              11. MEX Language Tutorial                                 183
  10182.  
  10183.               &         Bitwise and. This operator yields the bitwise and
  10184.                         of two integral operands. Each bit in the result
  10185.                         is a 1 only if the bits in the equivalent posi-
  10186.                         tions in both operands are both equal to 1.
  10187.  
  10188.               |         Bitwise or. This operator yields the bitwise or
  10189.                         of two integral operands. Each bit in the result
  10190.                         is a 1 if either of the bits in the equivalent
  10191.                         positions of the operands are equal to 1.
  10192.               shl       Shift-left. This operator shifts the left-hand
  10193.                         operand to the left by the number of bits speci-
  10194.                         fied by the right-hand operand. This operator im-
  10195.                         plements a logical shift and does not necessarily
  10196.                         preserve the sign of the operand, regardless of
  10197.                         whether it is signed or unsigned.
  10198.               shr       Shift-right. This operator shifts the left-hand
  10199.                         operand to the right by the number of bits speci-
  10200.                         fied by the right-hand operand. This operator im-
  10201.                         plements a logical shift; bits shifted in on the
  10202.                         left-hand side of the word are always 0.
  10203.  
  10204.  
  10205.              The normal mathematical order of evaluation applies to all
  10206.              calculations. (A table listing the exact operator precedence
  10207.              can be found in section 16.)
  10208.  
  10209.              When expressions involve operands which have different types,
  10210.              the operand with the smallest range is always promoted to the
  10211.              type of the other operand. If two operands are the same type
  10212.              but one is unsigned and the other is signed, the unsigned op-
  10213.              erand is always converted to a signed operand.
  10214.  
  10215.              This code demonstrates the simple arithmetic operators:
  10216.  
  10217.                 #include <max.mh>
  10218.  
  10219.                 int main()
  10220.                 {
  10221.                   int: i, j, k;
  10222.  
  10223.                   i := 3;
  10224.                   j := 4 * i;         // j = 12
  10225.                   k := j / 3 + 1;     // k = 5
  10226.  
  10227.                   return 0;
  10228.                 }
  10229.  
  10230.              In addition, parentheses can be used in any expression to ex-
  10231.              plicitly specify the order of evaluation:
  10232.  
  10233.                 #include <max.mh>
  10234.  
  10235.                 int main()
  10236.  
  10237.  
  10238.  
  10239.              11. MEX Language Tutorial                                 184
  10240.  
  10241.                 {
  10242.                   int: i, j, k;
  10243.  
  10244.                   i := 3;
  10245.                   j := 4 * i;         // j = 12
  10246.                   k := j / (3 + 1);   // k = 3
  10247.  
  10248.                   return 0;
  10249.                 }
  10250.  
  10251.              The logical operators are also quite useful for evaluating
  10252.              true/false expressions. Unlike other languages, MEX has no
  10253.              explicit "boolean" data type. Instead, any integral expres-
  10254.              sion can be evaluated as a boolean expression. Expressions
  10255.              which evaluate to zero are considered to be false, while all
  10256.              non-zero expressions are considered to be true. Boolean-like
  10257.              macro definitions for TRUE and FALSE can be found in max.mh.
  10258.  
  10259.              For example:
  10260.  
  10261.                 #include <max.mh>
  10262.  
  10263.                 int main()
  10264.                 {
  10265.                   int: i, j, k, l, m;
  10266.  
  10267.                   i := 0;
  10268.                   j := 4;
  10269.  
  10270.                   k := i and k;       // k = 0
  10271.                   l := i or j;        // l = 1
  10272.                   m := l and k;       // m = 0
  10273.  
  10274.                   return 0;
  10275.                 }
  10276.  
  10277.              Although MEX does not have an explicit not operator, it is
  10278.              easy to test if a boolean condition is false by simply com-
  10279.              paring it with 0:
  10280.  
  10281.                 #include <max.mh>
  10282.  
  10283.                 int main()
  10284.                 {
  10285.                   int: i, j, k, l;
  10286.  
  10287.                   i := 2;
  10288.                   j := 3;
  10289.                   k := (i = 3);     // k = 0 since i <> 3
  10290.                   l := (k = 0)      // l = not k = 1
  10291.  
  10292.                   return 0;
  10293.                 }
  10294.  
  10295.  
  10296.  
  10297.              11. MEX Language Tutorial                                 185
  10298.  
  10299.  
  10300.              Last but not least, the + operator can be used to catenate
  10301.              (combine) strings. For example:
  10302.  
  10303.                 #include <max.mh>
  10304.  
  10305.                 int main()
  10306.                 {
  10307.                   string: s1, s2, s3;
  10308.  
  10309.                   s1 := "Foo";
  10310.                   s2 := "Bar";
  10311.                   s3 := s1 + s2;      // s3 = "FooBar"
  10312.                   print(s3);
  10313.                   return 0;
  10314.                 }
  10315.  
  10316.              The string catenation operator can also be applied to multi-
  10317.              ple strings at a time:
  10318.  
  10319.                 #include <max.mh>
  10320.  
  10321.                 int main()
  10322.                 {
  10323.                   string: s1, s2, s3, s4;
  10324.  
  10325.                   s1 := "string1";
  10326.                   s2 := "string2";
  10327.                   s3 := "string3";
  10328.                   s4 := s1 + s2 + s3;
  10329.                   print(s4);
  10330.                   return 0;
  10331.                 }
  10332.  
  10333.              11.7. Displaying Output
  10334.  
  10335.              As seen in the sample program in the introduction, the print
  10336.              function is used to display output to the user. However,
  10337.              print is not limited to displaying just predefined text. The
  10338.              print function can also display the contents of variables and
  10339.              combine multiple data types into one statement.
  10340.  
  10341.              In general, multiple arguments can be used within a print
  10342.              statement by providing a comma-delimited list of variables or
  10343.              constants to be displayed. Providing such a list is equiva-
  10344.              lent to listing each variable in a sequence of separate print
  10345.              statements.
  10346.  
  10347.              In other words, given a declaration such as this:
  10348.  
  10349.                 string: a, b, c;
  10350.  
  10351.                 a := "Alpha ";
  10352.  
  10353.  
  10354.  
  10355.              11. MEX Language Tutorial                                 186
  10356.  
  10357.                 b := "Bravo ";
  10358.                 c := "Charlie ";
  10359.  
  10360.              the following code segment:
  10361.  
  10362.                 print(a, b, c);
  10363.  
  10364.              will display "Alpha Bravo Charlie ". However, the following
  10365.              code segment will also produce the same output:
  10366.  
  10367.                 print(a);
  10368.                 print(b);
  10369.                 print(c);
  10370.  
  10371.              However, print is not limited to displaying only strings.
  10372.              Both characters and integers can also be displayed:
  10373.  
  10374.                 #include <max.mh>
  10375.  
  10376.                 int main()
  10377.                 {
  10378.                   char: c;
  10379.                   int: i;
  10380.                   string: s;
  10381.  
  10382.                   s := "The best solution to the problem is ";
  10383.                   c := '#';
  10384.                   i := 1;
  10385.  
  10386.                   print(s, c, i);
  10387.                   return 0;
  10388.                 }
  10389.  
  10390.              This code will display:
  10391.  
  10392.                 The best solution to the problem is #1
  10393.  
  10394.              One further point is that the print function does not add any
  10395.              extra spacing when displaying variables. Had an extra space
  10396.              not been included at the end of the string s, the output
  10397.              would have appeared as follows:
  10398.  
  10399.                 The best solution to the problem is#1
  10400.  
  10401.              Similarly, the print function does not automatically move the
  10402.              cursor to the next line after displaying the specified vari-
  10403.              ables. If this cursor movement is desired, the newline escape
  10404.              sequence ('\n') should be inserted at the end of the print
  10405.              statement, as shown below:
  10406.  
  10407.                 string: s;
  10408.                 char: c;
  10409.  
  10410.  
  10411.  
  10412.              11. MEX Language Tutorial                                 187
  10413.  
  10414.                 s := "Text #";
  10415.                 c := '2';
  10416.  
  10417.                 print(s, c, '\n');
  10418.  
  10419.              This code will display "Text #2" and move the cursor to the
  10420.              beginning of the next line.
  10421.  
  10422.  
  10423.              11.8. Flow Control
  10424.  
  10425.              In the preceding MEX examples, the programs have all executed
  10426.              the statements in the main function from top to bottom. How-
  10427.              ever, we may want to execute only some of the statements en-
  10428.              closed in a function, or in some cases, we may want to repeat
  10429.              some of its statements more than once.
  10430.  
  10431.              The flow of a program is the order in which the computer exe-
  10432.              cutes statements within a function. Adding flow control
  10433.              statements to a MEX program allows the designer to modify the
  10434.              flow and specify the conditions necessary for groups of
  10435.              statements to be executed or iterated (repeated).
  10436.  
  10437.              There are two types of flow control statements: conditional
  10438.              statements and iterative statements. Conditional statements
  10439.              allow a set of statements to be executed or skipped based on
  10440.              a specified condition, while iterative statements allow a
  10441.              group of statements to be executed multiple times.
  10442.  
  10443.  
  10444.              11.8.1. Conditional Execution
  10445.  
  10446.              The most basic form of conditional flow control is the if
  10447.              statement. The if statement allows the conditional selection
  10448.              of a group of statements.
  10449.  
  10450.              The if statement has two separate forms. The standard form
  10451.              looks like this:
  10452.  
  10453.                 if (expr)
  10454.                   statement1
  10455.  
  10456.              If the expression inside the parentheses evaluates to non-
  10457.              zero, statement1 is executed. Otherwise, statement1 is
  10458.              skipped.
  10459.  
  10460.              The second form of the if statement looks like this:
  10461.  
  10462.                 if (expr)
  10463.                   statement1
  10464.                 else
  10465.                   statement2
  10466.  
  10467.  
  10468.  
  10469.              11. MEX Language Tutorial                                 188
  10470.  
  10471.              This is also referred to as the if / else statement. If expr
  10472.              evaluates to non-zero, only statement1 is executed. Other-
  10473.              wise, only statement2 is executed.
  10474.  
  10475.              Note that if itself is a statement, so multiple if / else
  10476.              statements can be chained together as shown below:
  10477.  
  10478.                 if (a+b > c)
  10479.                   print("a+b > c");
  10480.                 else if (b+c < a)
  10481.                   print("b+c < a");
  10482.                 else if (d*e = 0)
  10483.                   print("d*e = 0");
  10484.                 else
  10485.                   print("none of the above");
  10486.  
  10487.              In addition, the if statement can be used to conditionally
  10488.              execute multiple statements by using a compound statement. A
  10489.              compound statement is a pair of braces, between which can be
  10490.              any number of other statements. This means that constructs
  10491.              such as this can be used:
  10492.  
  10493.                 if (a > c)
  10494.                 {
  10495.                   print("a > c\n");
  10496.                   d := 0;
  10497.                 }
  10498.                 else
  10499.                 {
  10500.                   print("a <= c\n");
  10501.                   d := 1;
  10502.                 }
  10503.  
  10504.              In this example, if a is greater than c, MEX will display "a
  10505.              > c" and set d to 0. Otherwise, it will display "a <= 3" and
  10506.              set d to 1.
  10507.  
  10508.              The if statement can also be nested, as shown below:
  10509.  
  10510.                 if (a > c)
  10511.                 {
  10512.                   if (a > d)
  10513.                        print("a is bigger than c and d\n");
  10514.                   else
  10515.                        print("a is bigger than c only\n");
  10516.                 }
  10517.                 else
  10518.                   print("a is smaller than c\n");
  10519.  
  10520.  
  10521.  
  10522.              11. MEX Language Tutorial                                 189
  10523.  
  10524.              11.8.2. Iterative Flow Control
  10525.  
  10526.              Iteration is used when one or more statements need to be exe-
  10527.              cuted multiple times. Iteration is also known as looping or
  10528.              repetition.
  10529.  
  10530.              MEX supports three different types of iterative flow control:
  10531.              the while statement, the do .. while statement, and the for
  10532.              statement:
  10533.  
  10534.  
  10535.              11.8.2.1. while
  10536.  
  10537.              The simplest form of iteration is the while statement (or
  10538.              while loop). This statement instructs MEX to repeat the fol-
  10539.              lowing statement as long as a given expression is non-zero.
  10540.  
  10541.              A standard while statement looks like this:
  10542.  
  10543.                 while (expr)
  10544.                   statement1;
  10545.  
  10546.              As with the if statement, statement1 can be either a single
  10547.              statement or a compound statement.
  10548.  
  10549.              Before every iteration of the loop, including before the
  10550.              first iteration, expr is evaluated. If expr evaluates to
  10551.              zero, the loop is skipped. Otherwise, statement1 is executed
  10552.              once, and then the whole process repeats. (This implies that
  10553.              if expr is initially zero, the loop will never be executed.)
  10554.  
  10555.              For example, the following code fragment causes the body of
  10556.              the while loop, the "i := i + 1" statement, to execute ten
  10557.              times:
  10558.  
  10559.                 #include <max.mh>
  10560.  
  10561.                 int main()
  10562.                 {
  10563.                   int: i;
  10564.  
  10565.                   i := 1;
  10566.  
  10567.                   while (i <= 10)
  10568.                        i := i + 1;
  10569.  
  10570.                   return 0;
  10571.                 }
  10572.  
  10573.              The "i := i + 1" could have easily been replaced with a com-
  10574.              pound statement, such as one which increments the counter and
  10575.              then calls print to display the value of the counter:
  10576.  
  10577.  
  10578.  
  10579.              11. MEX Language Tutorial                                 190
  10580.  
  10581.                 #include <max.mh>
  10582.  
  10583.                 int main()
  10584.                 {
  10585.                   int: i;
  10586.  
  10587.                   i := 1;
  10588.  
  10589.                   while (i <= 10)
  10590.                   {
  10591.                        print("i = ", i, '\n');
  10592.                        i := i + 1;
  10593.                   }
  10594.  
  10595.                   return 0;
  10596.                 }
  10597.  
  10598.  
  10599.              11.8.2.2. do .. while
  10600.  
  10601.              Conceptually, the do .. while statement (or do .. while loop)
  10602.              is very similar to the while statement. A do .. while state-
  10603.              ment looks like this:
  10604.  
  10605.                 do
  10606.                   statement1
  10607.                 while (expr);
  10608.  
  10609.              The only difference between a do .. while statement and a
  10610.              standard while statement is the point in time at which expr
  10611.              is evaluated. With a do .. while statement, the statement
  10612.              statement1 is executed first, and then expr is tested. This
  10613.              means that the loop will always be iterated at least once,
  10614.              regardless of the value of expr.
  10615.  
  10616.                 #include <max.mh>
  10617.  
  10618.                 int main()
  10619.                 {
  10620.                   int: i;
  10621.  
  10622.                   i := 0;
  10623.  
  10624.                   do
  10625.                   {
  10626.                        print("i = ", i, '\n');
  10627.                        i := i + 1;
  10628.                   }
  10629.                   while (i > 0 and i <= 9);
  10630.  
  10631.                   return 0;
  10632.                 }
  10633.  
  10634.  
  10635.  
  10636.              11. MEX Language Tutorial                                 191
  10637.  
  10638.              This code will increment i from 1 to 10, as in the previous
  10639.              example. However, the loop condition has been modified so
  10640.              that the loop will exit if "i > 0 and i <= 10" is false.
  10641.  
  10642.              On the first iteration, i is set to zero. However, the loop
  10643.              condition is not tested until the end of the loop, after i
  10644.              has been incremented to 1, so the loop condition is true.
  10645.  
  10646.  
  10647.              11.8.2.3. for
  10648.  
  10649.              The for statement (or the for loop) is also quite similar to
  10650.              the while statement, but the for statement allows the loop
  10651.              initialization and termination conditions to be written in a
  10652.              much more concise manner.
  10653.  
  10654.              A for statement looks like this:
  10655.  
  10656.                 for (initexpr; testexpr; postexpr)
  10657.                   statement1;
  10658.  
  10659.              When processing a for loop,  the compiler will proceed as
  10660.              follows:
  10661.  
  10662.              1. Before anything else is done, initexpr is evaluated. Since
  10663.                 this expression is evaluated only once, it is commonly used
  10664.                 to initialize a variable used in the loop test. (Note that
  10665.                 "expressions" such as this can include assignments and
  10666.                 function calls.)
  10667.  
  10668.              2. Next, testexpr is evaluated. If this expression evaluates
  10669.                 to zero, the loop is skipped.
  10670.  
  10671.              3. statement1 is executed. This statement is also known the
  10672.                 body of the loop. Overall, statement1 is continually exe-
  10673.                 cuted as long as testexpr evaluates to non-zero.
  10674.  
  10675.              4. postexpr is evaluated. This expression is normally used to
  10676.                 increment some sort of loop counter.
  10677.  
  10678.              5. Branch back to step 2.
  10679.  
  10680.              A simple for statement looks like this:
  10681.  
  10682.                 for (i := 1; i <= 10; i := i + 1)
  10683.                   print("i = ", i, '\n');
  10684.  
  10685.              This loop simply counts from one to ten, displaying the value
  10686.              of i while doing so. To break down the loop operation in de-
  10687.              tail:
  10688.  
  10689.              1. Before the loop begins, i is initialized to 1.
  10690.  
  10691.  
  10692.  
  10693.              11. MEX Language Tutorial                                 192
  10694.  
  10695.              2. Next, i is compared with ten. This test succeeds, so the
  10696.                 print statement in the body of the loop is executed.
  10697.  
  10698.              3. i is then incremented by one.
  10699.  
  10700.              4. The whole process repeats by comparing i with ten, and then
  10701.                 performing the actions from 2 through 4 again.
  10702.  
  10703.              From this, one can see that the for statement is just a
  10704.              shorthand notation for the while statement. An equivalent
  10705.              representation for the for statement is shown below:
  10706.  
  10707.                 initexpr;
  10708.  
  10709.                 while (testexpr)
  10710.                 {
  10711.                   statement1;
  10712.                   postexpr;
  10713.                 }
  10714.  
  10715.              11.8.3. Goto and Labels
  10716.  
  10717.              There are few cases when the preceding flow-control state-
  10718.              ments cannot be used to implement an arbitrary program struc-
  10719.              ture.  However, for those rare cases when the preceding
  10720.              statements are not sufficient, MEX provides a goto statement.
  10721.  
  10722.              The goto statement unconditionally transfers program control
  10723.              to a specific point in the program. The goto statement can be
  10724.              used to jump to another statement that either precedes or
  10725.              follows the goto statement itself, as long as the destination
  10726.              of the jump is within the same function as the goto.
  10727.  
  10728.              The goto statement is often said to be the antithesis of
  10729.              structured programming, but when used very sparingly, it can
  10730.              sometimes simplify error-handling or allow the programmer to
  10731.              exit a deeply-nested loop.
  10732.  
  10733.              A goto statement looks like this:
  10734.  
  10735.                 goto label;
  10736.  
  10737.              where label is the user-defined destination for the jump.
  10738.  
  10739.              A label declaration looks like this:
  10740.  
  10741.                 labelname:
  10742.  
  10743.              where labelname is an arbitrary name that follows these con-
  10744.              ventions:
  10745.  
  10746.              *  The name must be from 1 to 32 characters long.
  10747.  
  10748.  
  10749.  
  10750.              11. MEX Language Tutorial                                 193
  10751.  
  10752.              *  The name is case-sensitive. This means that "delta,"
  10753.                 "Delta," "DELTA," and "DeLtA" refer to four distinct ob-
  10754.                 jects.
  10755.  
  10756.              *  Names can include letters and underscores. Names can also
  10757.                 include digits, except in the first character of the name.
  10758.                 (This means that "top10" is a valid name, whereas "7up" is
  10759.                 not.)
  10760.  
  10761.              The labelname is used to specify the destination in the goto
  10762.              statement. When the program encounters a "goto labelname"
  10763.              statement, it will immediately jump to the statement follow-
  10764.              ing labelname.
  10765.  
  10766.              The following code fragment demonstrates how goto is used to
  10767.              break out of a for loop:
  10768.  
  10769.                 #include <max.mh>
  10770.  
  10771.                 int main()
  10772.                 {
  10773.                   int: i, sum;
  10774.  
  10775.                   // Start sum off at zero.
  10776.  
  10777.                   sum := 0;
  10778.  
  10779.                   // Count from 1 to 10
  10780.  
  10781.                   for (i := 0; i <= 10; i := i+1)
  10782.                   {
  10783.                        // Increment sum by the value of the counter.
  10784.  
  10785.                        sum := sum+i;
  10786.  
  10787.                        // If the count is at least 14, exit
  10788.                        // the loop.
  10789.  
  10790.                        if (sum >= 14)
  10791.                             goto out;
  10792.                   }
  10793.  
  10794.                 out:
  10795.                   print(sum);
  10796.                   return 0;
  10797.                 }
  10798.  
  10799.              There are much more elegant ways to implement this function,
  10800.              such as by moving the sum check into the testexpr of the for
  10801.              loop. Regardless, this code fragment shows how to add up all
  10802.              of the numbers from one to ten, but exiting the loop as soon
  10803.              as sum is greater than or equal to 14. (In the case above,
  10804.              sum will equal 15 when the loop finally terminates.)
  10805.  
  10806.  
  10807.  
  10808.              11. MEX Language Tutorial                                 194
  10809.  
  10810.              11.9. Function Calls
  10811.  
  10812.              As previously described in section 11.2.1, functions are the
  10813.              main building blocks of MEX programs. All MEX programs must
  10814.              contain a main function, but most programs will also have
  10815.              many other related functions. These functions are used to
  10816.              break a large problem down into smaller, more-manageable
  10817.              parts.
  10818.  
  10819.              In addition to the functions defined in the .mex source file,
  10820.              a large number of external functions can also be called by a
  10821.              MEX program. These functions perform various actions such as:
  10822.              displaying output to the user, prompting the user for input,
  10823.              accessing the Maximus user file, manipulating the file tag
  10824.              queue, and more. The code for these functions is contained
  10825.              within Maximus itself, but the functions can be called just
  10826.              like ordinary MEX functions declared in the source file. (A
  10827.              complete list of external functions is contained in section
  10828.              15.)
  10829.  
  10830.              In this section, the calling function refers to the point in
  10831.              the code from which a function call is made. The called func-
  10832.              tion refers to the destination of a function call, or the
  10833.              code that gets executed when the function call is performed.
  10834.  
  10835.              This section describes how to call functions, how to write
  10836.              your own functions, and how to pass data from one function to
  10837.              another.
  10838.  
  10839.  
  10840.              11.9.1. Calling Functions
  10841.  
  10842.              A function call looks like this:
  10843.  
  10844.                 funcname(arglist);
  10845.  
  10846.              funcname is the name of the function to call. This name sim-
  10847.              ply identifies a function that has already been declared or
  10848.              defined in either the .mex source file or in the global
  10849.              max.mh header file.
  10850.  
  10851.              arglist is an optional, comma-delimited list of arguments to
  10852.              be used in the function call. Arguments are data objects that
  10853.              are shared between functions. Arguments allow the calling
  10854.              function to communicate with the called function, and vice
  10855.              versa.
  10856.  
  10857.              Although the comma-delimited list of arguments is optional,
  10858.              the pair of parentheses is not. Even if a function accepts no
  10859.              arguments, an empty pair of parentheses must follow the func-
  10860.              tion name.
  10861.  
  10862.  
  10863.  
  10864.              11. MEX Language Tutorial                                 195
  10865.  
  10866.              In the calling function, a function call can be written ei-
  10867.              ther as a separate statement (as shown above), or for func-
  10868.              tions that return values, the call can also be included in
  10869.              expressions. This is discussed in more detail in section
  10870.              11.9.4.
  10871.  
  10872.              Normally, arguments are used for one-way information transfer
  10873.              (to send information from the calling code to the function
  10874.              that is called), but if desired, the function arguments can
  10875.              also be used to transfer information in the other direction.
  10876.  
  10877.              The function call syntax should already be familiar, since
  10878.              the print function (as was used in many of the code segments
  10879.              given in prior sections) is just one example of a function
  10880.              call.
  10881.  
  10882.              When a MEX program encounters a function call, the following
  10883.              steps are taken:
  10884.  
  10885.              1. The current program location is saved.
  10886.  
  10887.              2. The arguments specified in arglist are copied so that the
  10888.                 called function can access the information therein.
  10889.  
  10890.              3. Control is transferred to the called function. The state-
  10891.                 ments in the called function are executed until it issues a
  10892.                 return statement or executes the very last statement in the
  10893.                 function.
  10894.  
  10895.              4. The program location is restored to the position saved in
  10896.                 step 1.
  10897.  
  10898.              For example, the following example demonstrates how to se-
  10899.              quentially call a number of functions. (The declarations for
  10900.              these functions will be discussed in the following section.)
  10901.  
  10902.                 #include <max.mh>
  10903.  
  10904.                 // insert function definitions here
  10905.  
  10906.                 int main()
  10907.                 {
  10908.                   initialize_data();
  10909.                   open_file();
  10910.                   write_file();
  10911.                   close_file();
  10912.                   deinitialize_data();
  10913.                   return 0;
  10914.                 }
  10915.  
  10916.              In this case, the main function is nothing but an empty shell
  10917.              that calls other functions. The above code instructs main to
  10918.              execute the statements in the initialize_data, open_file,
  10919.  
  10920.  
  10921.  
  10922.              11. MEX Language Tutorial                                 196
  10923.  
  10924.              write_file, close_file and deinitialize_data functions, in
  10925.              the order specified above.
  10926.  
  10927.              The called functions can also include function calls in their
  10928.              own code, and the functions called from there can also call
  10929.              other functions. In theory, an infinite number of function
  10930.              calls can be nested in this manner, but in practice, only a
  10931.              few dozen nested calls can be made at a time, depending on
  10932.              the size of the function arguments and the stack size speci-
  10933.              fied on the MEX command line.
  10934.  
  10935.              The print function is just one example of a function that re-
  10936.              quires arguments. Some functions can also accept multiple ar-
  10937.              guments, as shown below:
  10938.  
  10939.                 #include <max.mh>
  10940.  
  10941.                 // insert function definitions here
  10942.  
  10943.                 int main()
  10944.                 {
  10945.                   int: sailors;
  10946.                   int: yachts;
  10947.  
  10948.                   sailors := 8;
  10949.                   yachts := 2;
  10950.  
  10951.                   initialize_data(sailors, yachts);
  10952.  
  10953.                   sail_yacht_1(sailors / yachts);
  10954.                   sail_yacht_2(sailors - (sailors / yachts));
  10955.  
  10956.                   return 0;
  10957.                 }
  10958.  
  10959.              The first two statements initialize the variables sailors and
  10960.              yachts to 8 and 2, respectively.
  10961.  
  10962.              The next statement is a function call to initialize_data. The
  10963.              two variables sailors and yachts are passed as arguments. In
  10964.              this hypothetical example, the initialize_data function pre-
  10965.              sumably uses these values to set up data structures describ-
  10966.              ing the number of sailors and the number of yachts that are
  10967.              in use.
  10968.  
  10969.              Next, the sail_yacht_1 function is called, with a number rep-
  10970.              resenting about half of the sailors. The function could use
  10971.              that information to determine how many sailors were in the
  10972.              boat's crew.
  10973.  
  10974.              Finally, the sail_yacht_2 function is called, using the num-
  10975.              ber of remaining sailors as an argument. The function would
  10976.  
  10977.  
  10978.  
  10979.              11. MEX Language Tutorial                                 197
  10980.  
  10981.              also presumably use the number of sailors to determine how it
  10982.              operates.
  10983.  
  10984.              As can be seen from the example above, although functions are
  10985.              used to break up the code of a program into smaller parts,
  10986.              the function argument list is how information is passed from
  10987.              one function to another.
  10988.  
  10989.  
  10990.              11.9.2. Defining Functions
  10991.  
  10992.              Previous sections have focused on calling external functions,
  10993.              or as-of-yet undeclared and undefined functions in the user
  10994.              code. This section describes how to define functions of one's
  10995.              own that can be called from other points in the program.
  10996.  
  10997.              A function definition has this form:
  10998.  
  10999.                 return_type funcname(paramlist)
  11000.                 {
  11001.                   statements
  11002.                 }
  11003.  
  11004.              This definition can be broken down as follows:
  11005.  
  11006.              return_type is the type used for the function's return value.
  11007.              The return value is an optional piece of information that is
  11008.              passed back to the calling function. (If desired, the func-
  11009.              tion arguments can also be used to pass information back to
  11010.              the caller.) Not all functions have return values; when that
  11011.              is the case, the return_type is "void."
  11012.  
  11013.              funcname is the name of the function. This name is used when
  11014.              calling this function via a function call. Function names
  11015.              must abide by the following conventions:
  11016.  
  11017.              *  The name must be from 1 to 32 characters long.
  11018.  
  11019.              *  The name is case-sensitive. This means that "delta,"
  11020.                 "Delta," "DELTA," and "DeLtA" refer to four distinct ob-
  11021.                 jects.
  11022.  
  11023.              *  Names can include letters and underscores. Names can also
  11024.                 include digits, except in the first character of the name.
  11025.                 (This means that "top10" is a valid name, whereas "7up" is
  11026.                 not.)
  11027.  
  11028.              paramlist is the optional, comma-delimited parameter list for
  11029.              the function. The parameter list consists of pairs of parame-
  11030.              ter types and parameter names. For functions that accept no
  11031.              parameters, the space within the parentheses must be left
  11032.              blank. The topic of function parameters is discussed in the
  11033.              following section in greater detail.
  11034.  
  11035.  
  11036.  
  11037.              11. MEX Language Tutorial                                 198
  11038.  
  11039.              The pair of braces delimit the body of the function. The
  11040.              statements contained therein can be any of the statement
  11041.              types described in previous sections.
  11042.  
  11043.              However, function definitions may not be nested. This means
  11044.              that function definitions must be placed at the "top level"
  11045.              of the source file, outside of any other function defini-
  11046.              tions.
  11047.  
  11048.              A simple function definition looks something like this:
  11049.  
  11050.                 void hokey_pokey()
  11051.                 {
  11052.                   print("bar\n");
  11053.                 }
  11054.  
  11055.              This code defines a function called hokey_pokey. This func-
  11056.              tion can be called from the main function as shown below:
  11057.  
  11058.                 int main()
  11059.                 {
  11060.                   print("foo\n");
  11061.                   hokey_pokey();
  11062.                   print("boz\n");
  11063.  
  11064.                   return 0;
  11065.                 }
  11066.  
  11067.              When run, this program will print:
  11068.  
  11069.                 foo
  11070.                 bar
  11071.                 boz
  11072.  
  11073.  
  11074.              11.9.3. Function Prototypes
  11075.  
  11076.              If the called function is not defined in the same program
  11077.              source file as the calling function (such as with external
  11078.              functions), or if the function is defined later in the same
  11079.              file, the compiler must be told some extra information about
  11080.              the called function, including its argument types and return
  11081.              value.
  11082.  
  11083.              Regardless of whether a function is internal or external, the
  11084.              compiler needs some sort of information about the function ---
  11085.              either a function definition or a function prototype ---be-
  11086.              fore that function can be called.
  11087.  
  11088.              If an external function is called, a function prototype is
  11089.              required. If an internal function is called, and the defini-
  11090.              tion of that function occurs at a later point in the source
  11091.              file than the function call itself, a function prototype is
  11092.  
  11093.  
  11094.  
  11095.              11. MEX Language Tutorial                                 199
  11096.  
  11097.              also required. (If the called function is defined in the same
  11098.              file, and the definition occurs above the point in the file
  11099.              where it is called, a prototype is not required. In this
  11100.              case, the function definition provides sufficient information
  11101.              to the compiler.)
  11102.  
  11103.              A function prototype looks just like a function definition,
  11104.              except that the prototype has no function body. Instead, the
  11105.              statements and braces are replaced with a single semicolon.
  11106.  
  11107.              A function prototype looks like this:
  11108.  
  11109.                 type funcname(paramlist);
  11110.  
  11111.              type is the return type of the function. This type must match
  11112.              the return type given in the function definition.
  11113.  
  11114.              funcname is the name of the function. This too should match
  11115.              the name of the function given in the function definition.
  11116.  
  11117.              paramlist is the parameter list for the function. Except in
  11118.              special cases with variable-parameter functions, this list
  11119.              should also match the parameter list given in the function
  11120.              definition.
  11121.  
  11122.              Function prototypes must be placed at the "top level" of the
  11123.              source file, outside of any other function definition, and
  11124.              before any attempt is made to call the function being proto-
  11125.              typed.
  11126.  
  11127.              Since a prototype tells the compiler about a function, before
  11128.              the definition for that function is presented, using proto-
  11129.              types allows two functions to call each other recursively:
  11130.  
  11131.                 #include <max.mh>
  11132.  
  11133.                 void func2();         // Prototype for func2
  11134.  
  11135.                 void func1()
  11136.                 {
  11137.                   func2();       // Call func2, even though it has
  11138.                                  // been declared. (The prototype
  11139.                                  // above tells the compiler about
  11140.                                  // func2 and the arguments/return
  11141.                                  // value that it accepts.
  11142.                 }
  11143.  
  11144.                 void func2()
  11145.                 {
  11146.                   func1();       // Call func1. A prototype is not
  11147.                                  // required because the function
  11148.                                  // was defined at an earlier
  11149.                                  // point in the same file.
  11150.  
  11151.  
  11152.  
  11153.              11. MEX Language Tutorial                                 200
  11154.  
  11155.                 }
  11156.  
  11157.              Note that for all of the external functions described in sec-
  11158.              tion 15, the appropriate function prototypes are already in-
  11159.              cluded in the max.mh include file. Hence, as long as the pro-
  11160.              gram contains the crucial "#include <max.mh>" line at the top
  11161.              of the file, all of the external functions will be automati-
  11162.              cally prototyped.
  11163.  
  11164.  
  11165.              11.9.4. Function Arguments
  11166.  
  11167.  
  11168.              11.9.4.1. Pass-By-Value Arguments
  11169.  
  11170.              Up until now, functions have been treated as if they were
  11171.              simply logical blocks of a program, performing the same pur-
  11172.              pose each time they were called. Function arguments allow
  11173.              functions to perform different actions depending on the val-
  11174.              ues of their arguments.
  11175.  
  11176.              An important distinction must be made between function argu-
  11177.              ments and function parameters. From the calling function, the
  11178.              variables specified when writing the function call are known
  11179.              as arguments. Within the called function, these arguments are
  11180.              referred to as parameters. This implies that the arguments
  11181.              that are "sent" by the calling function are equivalent to the
  11182.              parameters that are "received" by the called function.
  11183.  
  11184.              A function can accept as many parameters as desired; however,
  11185.              each parameter (and its associated type) must be specified
  11186.              when the function is defined and prototyped.
  11187.  
  11188.              A definition for a function that has parameters looks like
  11189.              this:
  11190.  
  11191.                 type funcname(type1: var1, type2: var2)
  11192.                 {
  11193.                   statements;
  11194.                 }
  11195.  
  11196.              In this case, type1 is the type of the first parameter, and
  11197.              var1 is the name used to reference the parameter.
  11198.  
  11199.              Similarly, type2 is the type of the second parameter, and
  11200.              var2 is the name used to reference the second parameter.
  11201.  
  11202.              Naturally, more than two parameters can be used by simply ex-
  11203.              panding the comma-delimited list to provide more than two pa-
  11204.              rameter type/name pairs. The comma-delimited list is also
  11205.              known as the function's parameter list.
  11206.  
  11207.  
  11208.  
  11209.              11. MEX Language Tutorial                                 201
  11210.  
  11211.              A special word of caution is required for function parame-
  11212.              ters:
  11213.  
  11214.              All function arguments and parameters are positional. This
  11215.              means that the first parameter in a function definition must
  11216.              correspond to the first argument passed in a call to that
  11217.              function. Similar logic applies to the second and subsequent
  11218.              arguments and parameters.
  11219.  
  11220.              Also, the parameter names specified in the called function
  11221.              are simply "dummy names." The value to use for each parameter
  11222.              is provided by the argument list from the calling function.
  11223.              The calling function can pass any variable or expression for
  11224.              a given argument, but that value will become known to the
  11225.              called function by the parameter name specified in the func-
  11226.              tion definition.
  11227.  
  11228.              For example, given the following code:
  11229.  
  11230.                 #include <max.mh>
  11231.  
  11232.                 void myfunc(int: arg1, int: arg2)
  11233.                 {
  11234.                   print("arg1 = ", arg1, " and arg2 = ", arg2, '\n');
  11235.                 }
  11236.  
  11237.                 int main()
  11238.                 {
  11239.                   int: i, j;
  11240.  
  11241.                   i := 4;
  11242.                   j := 7;
  11243.  
  11244.                   myfunc(i, j);
  11245.                   return 0;
  11246.                 }
  11247.  
  11248.              The program output will be:
  11249.  
  11250.                 arg1 = 4 and arg2 = 7
  11251.  
  11252.              In the main function, the variable i is passed for arg1, and
  11253.              the variable j is passed for arg2. Within myfunc, the arg1
  11254.              and arg2 names refer to the parameters specified in the call
  11255.              to that function, regardless of what those arguments were
  11256.              called in the calling function.
  11257.  
  11258.              In myfunc, the value of arg1 will be equal to the value of i
  11259.              (from the main function), and the value of arg2 will be equal
  11260.              to the value of j (also from the main function).
  11261.  
  11262.  
  11263.  
  11264.              11. MEX Language Tutorial                                 202
  11265.  
  11266.              However, within the called function, changes made to the
  11267.              function parameters do not automatically cause a change in
  11268.              the arguments specified in the calling function.
  11269.  
  11270.              For example, given the following program:
  11271.  
  11272.                 #include <max.mh>
  11273.  
  11274.                 void change_it(int: a)
  11275.                 {
  11276.                   a := 3;
  11277.                 }
  11278.  
  11279.                 int main()
  11280.                 {
  11281.                   int: i;
  11282.  
  11283.                   i := 5;
  11284.                   change_it(i);
  11285.                   print("i is ", i, '\n');
  11286.                   return 0;
  11287.                 }
  11288.  
  11289.              This program prints:
  11290.  
  11291.                 i is 5
  11292.  
  11293.              As can be seen from the output, the assignment to a in
  11294.              change_it has no effect on the value of i in main.
  11295.  
  11296.  
  11297.              11.9.4.2. Pass-By-Reference Arguments
  11298.  
  11299.              MEX also supports a type of argument passing called pass-by-
  11300.              reference. Pass-by-reference arguments explicitly cause the
  11301.              argument passed into the function call to be modified when
  11302.              the parameter is updated from within the called function.
  11303.  
  11304.              To declare a pass-by-reference argument in the function defi-
  11305.              nition and prototype, simply include the ref keyword before
  11306.              the parameter type. For example, if the definition for
  11307.              change_it were modified to look like this:
  11308.  
  11309.                 void change_it(ref int: a)
  11310.  
  11311.              then the program would display:
  11312.  
  11313.                 i is 3
  11314.  
  11315.              as could be expected. The only caveat to using pass-by-
  11316.              reference arguments is that a variable must always be speci-
  11317.              fied for that argument when writing the function call, rather
  11318.              than using a constant or some other expression.
  11319.  
  11320.  
  11321.  
  11322.              11. MEX Language Tutorial                                 203
  11323.  
  11324.              This means that, given the pass-by-reference definition of
  11325.              change_it, the following function calls are illegal:
  11326.  
  11327.                 change_it(3);           // 3 is a constant
  11328.                 change_it(i * 2 + 2);   // i * 2 + 1 is an expression
  11329.  
  11330.              A function with pass-by-reference parameters will update the
  11331.              function argument if the parameter is changed from within the
  11332.              called function. Obviously, the function cannot change the
  11333.              "value" of the number 3. Likewise, it also cannot change the
  11334.              "value" of the expression "i * 2 + 1."
  11335.  
  11336.              Hence, arguments passed for pass-by-reference arguments must
  11337.              be simple variable names and not expressions or constants.
  11338.  
  11339.  
  11340.              11.9.5. Function Return Values
  11341.  
  11342.              In all of the examples presented in previous sections, the
  11343.              functions had no return value. A return value is another
  11344.              method that can be used to pass information from the called
  11345.              function back to the calling function.
  11346.  
  11347.              Function return values can be used in a manner similar to
  11348.              conventional mathematical functions. For example, if we had a
  11349.              function that calculated the square root of a number, one
  11350.              would like to be able to write:
  11351.  
  11352.                 i := sqrt(25);          // i = 5
  11353.  
  11354.              To declare a function that returns a value:
  11355.  
  11356.              1. In the function prototype and definition, select an appro-
  11357.                 priate return type for the function. This type must immedi-
  11358.                 ately precede the funcname part of the definition or proto-
  11359.                 type, as discussed in the preceding section.
  11360.  
  11361.              2. Inside the function, the return statement must be used to
  11362.                 identify the value being returned.
  11363.  
  11364.              A return statement looks like this:
  11365.  
  11366.                 return opt-expr;
  11367.  
  11368.              where opt-expr is an optional expression which has a type
  11369.              equivalent to the function return type.
  11370.  
  11371.              In those special cases where the function is declared as re-
  11372.              turning void, meaning that the function does not return a
  11373.              value, the opt-expr must not be present. If that is the case,
  11374.              the return statement must look like this:
  11375.  
  11376.                 return;
  11377.  
  11378.  
  11379.  
  11380.              11. MEX Language Tutorial                                 204
  11381.  
  11382.  
  11383.              For functions that are declared as returning void, the return
  11384.              statement simply instructs the function to return immediately
  11385.              to the calling function. No data is passed from the called
  11386.              function to the caller.
  11387.  
  11388.              In cases where the function does return a value, upon encoun-
  11389.              tering a return statement, the program will take the expres-
  11390.              sion indicated in the return statement and store its value so
  11391.              that the calling function can access it. The program will
  11392.              then immediately return to the calling function.
  11393.  
  11394.              For example, to implement the square root function from
  11395.              above:
  11396.  
  11397.                 int sqrt(int: value)  // the "int" before the sqrt
  11398.                 {                // identifies the type of
  11399.                                  // return value.
  11400.                   int: result;
  11401.  
  11402.                   // Code here that calculates the square root
  11403.                   // of 'value' and places the result in 'result.'
  11404.  
  11405.                   return result;
  11406.                 }
  11407.  
  11408.              In this case, the function is said to return the value that
  11409.              is contained in the result variable. The naming of the vari-
  11410.              able used in the return statement is completely arbitrary;
  11411.              the variable can be named anything, just as long as the re-
  11412.              turn statement indicates the value to be returned.
  11413.  
  11414.              However, the return statement need not always be at the very
  11415.              end of the function. Since the return function causes the
  11416.              program to immediately end the function being called, the re-
  11417.              turn statement is useful for error-checking and aborting a
  11418.              function before all statements have been executed.
  11419.  
  11420.              For example, to add a degree of error-checking to our func-
  11421.              tion:
  11422.  
  11423.                 #include <max.mh>
  11424.  
  11425.                 int sqrt(int: value)
  11426.                 {
  11427.                   int: result;
  11428.  
  11429.                   if (value < 0)
  11430.                   {
  11431.                        print("Invalid sqrt() argument!\n");
  11432.  
  11433.                        return -1;  // No real-valued number will
  11434.                                  // have this root.
  11435.  
  11436.  
  11437.  
  11438.              11. MEX Language Tutorial                                 205
  11439.  
  11440.                   }
  11441.  
  11442.                   // Code to place the root of 'value' into 'result'.
  11443.  
  11444.                   return result;
  11445.                 }
  11446.  
  11447.              In the case shown above, if an invalid argument is passed to
  11448.              the sqrt function, it will print an error message and return
  11449.              a value of -1. Otherwise, it will proceed with the calcula-
  11450.              tion and return the square root of the number.
  11451.  
  11452.              From this, one can see that the main function from previous
  11453.              examples is an ordinary function that returns an integer
  11454.              value. The only difference between main and other functions
  11455.              is that Maximus will check the return value from main, and if
  11456.              it is non-zero, Maximus will place an entry in the system
  11457.              log. (main is also the function that Maximus first calls when
  11458.              a MEX program is started.)
  11459.  
  11460.              However, functions are not constrained to returning only in-
  11461.              tegers. Functions can also be used to return data of types
  11462.              char, int, long and string. For example, to define a function
  11463.              that returns a string describing the day of the week:
  11464.  
  11465.                 string weekday(int: daynum)
  11466.                 {
  11467.                   if (daynum = 1)
  11468.                        return "Sunday";
  11469.                   else if (daynum = 2)
  11470.                        return "Monday";
  11471.                   else if (daynum = 3)
  11472.                        return "Tuesday";
  11473.                   else if (daynum = 4)
  11474.                        return "Wednesday";
  11475.                   else if (daynum = 5)
  11476.                        return "Thursday";
  11477.                   else if (daynum = 6)
  11478.                        return "Friday";
  11479.                   else if (daynum = 7)
  11480.                        return "Saturday";
  11481.                   else
  11482.                        return "*InvalidDay*";
  11483.                 }
  11484.  
  11485.              Compared to previous examples in this section, the only sig-
  11486.              nificant changes are that the function return value is de-
  11487.              clared as "string," and the values following the return
  11488.              statements are all string constants.
  11489.  
  11490.              The main restriction with return values is that only one data
  11491.              item can be returned to the caller. However, if multiple data
  11492.  
  11493.  
  11494.  
  11495.              11. MEX Language Tutorial                                 206
  11496.  
  11497.              items need to be passed back to the caller, pass-by-reference
  11498.              arguments are the obvious solution.
  11499.  
  11500.  
  11501.              11.10. Arrays
  11502.  
  11503.              Programs often need to manipulate large amounts of informa-
  11504.              tion in a similar manner. If a program needed to manipulate
  11505.              500 numbers, the programmer could easily declare a variable
  11506.              to hold each individual number:
  11507.  
  11508.                 int: num1;
  11509.                 int: num2;
  11510.                 int: num3;
  11511.                 // and so on
  11512.  
  11513.              However, if all of the numbers represented similar pieces of
  11514.              information (such as, say, the height of an office building),
  11515.              an array can greatly simplify the code used to manipulate
  11516.              this information.
  11517.  
  11518.              An array is a data type that holds collections of other data
  11519.              objects. All of the objects contained within an array must be
  11520.              of the same data type.
  11521.  
  11522.              In addition, the objects within the array can be indexed. For
  11523.              example, given an array of 500 numbers, the program can ex-
  11524.              plicitly retrieve the 42nd number. Arrays can also be indexed
  11525.              by another variable. For example, the program can ask to re-
  11526.              trieve the ith number from within the structure, and if the
  11527.              integer variable i happens to contain the value 3 at run-
  11528.              time, the third object in the array is retrieved.
  11529.  
  11530.              Arrays can be considered as a group of data objects all lined
  11531.              up in a row. Each object in that row can be accessed indi-
  11532.              vidually by number, but the entire row can still be referred
  11533.              to as a single array of objects.
  11534.  
  11535.  
  11536.              11.10.1. Declaring Arrays
  11537.  
  11538.              An array declaration looks like this:
  11539.  
  11540.                 array [lower .. upper] of type: varname;
  11541.  
  11542.              lower specifies the lower bound of the array. This is the
  11543.              lowest index value that can be used to store information in
  11544.              the array. Since most counting exercises start at the number
  11545.              one (as in first, second, third, and so on), this value is
  11546.              normally set to 1. (However, the code generated by the MEX
  11547.              compiler will run a little faster if the lower bound of the
  11548.              array is set to 0.)
  11549.  
  11550.  
  11551.  
  11552.              11. MEX Language Tutorial                                 207
  11553.  
  11554.              upper specifies the upper bound of the array. This is the
  11555.              highest possible index value that can be used to store infor-
  11556.              mation in the array. The value used for upper depends on the
  11557.              number of data items that need to be stored in the array. up-
  11558.              per must be greater than or equal to the value specified for
  11559.              lower.
  11560.  
  11561.              All of the values between lower and upper (inclusive) can be
  11562.              used as indices for the array. In general, the total number
  11563.              of data objects stored in the array can be calculated as fol-
  11564.              lows:
  11565.  
  11566.                 Number of objects = upper - lower + 1
  11567.  
  11568.              A data object within an array is also sometimes referred to
  11569.              as an element in the array.
  11570.  
  11571.              type is the data type of the objects contained in the array.
  11572.              As discussed earlier, all of the objects in the array will
  11573.              have the same type.
  11574.  
  11575.              varname is the name of the array variable to be declared.
  11576.              varname must abide by the standard MEX variable-naming rules.
  11577.  
  11578.              For example, this declaration creates an array of 100 inte-
  11579.              gers:
  11580.  
  11581.                 array [1 .. 100] of int: my_ints;
  11582.  
  11583.              In this case, the array variable is called my_ints, and valid
  11584.              index values are 1 through 100.
  11585.  
  11586.              Arrays of other data types can also be created; the indices
  11587.              for the array can also include negative values:
  11588.  
  11589.                 array [-50 .. 50] of string: my_strings;
  11590.  
  11591.              Here, the array variable is called my_strings, and valid in-
  11592.              dex values are -50 through 50.
  11593.  
  11594.  
  11595.              11.10.2. Accessing Arrays
  11596.  
  11597.              Array variables themselves cannot be assigned or used in
  11598.              arithmetic expressions. However, the data objects within the
  11599.              array can be assigned to, manipulated, displayed, and treated
  11600.              like any other kind of variable.
  11601.  
  11602.              After having declared an array, the array operator is used to
  11603.              access an individual data object within the array. Within an
  11604.              expression, the array operator is used like this:
  11605.  
  11606.                 arrayvar[idx]
  11607.  
  11608.  
  11609.  
  11610.              11. MEX Language Tutorial                                 208
  11611.  
  11612.  
  11613.              arrayvar is the name of a previously-declared array variable,
  11614.              such as my_ints or my_strings.
  11615.  
  11616.              idx is the index to be applied to the array, surrounded by
  11617.              square brackets. idx can be a constant (such as the number
  11618.              "4"), a variable (such as an integer), or the result of a
  11619.              more complex expression.
  11620.  
  11621.              This index value must always be within the bounds specified
  11622.              by upper and lower (from the array variable declaration). Us-
  11623.              ing an out-of-bounds index value results in undefined behav-
  11624.              ior.
  11625.  
  11626.              When used with the array operator, the arrayvar and idx vari-
  11627.              ables select a single data object from within the array. The
  11628.              array operator is always used as part of an expression. After
  11629.              applying the array operator, the resulting object can then be
  11630.              assigned to, manipulated as part of another expression,
  11631.              passed as a function argument, and treated like any other
  11632.              variable.
  11633.  
  11634.              For example, given the my_ints array declaration from above,
  11635.              the contents of the array can be set up as shown below:
  11636.  
  11637.                 my_ints[1] := 42;
  11638.                 my_ints[2] := 119;
  11639.                 my_ints[3] := 55;
  11640.                 // and so on
  11641.  
  11642.              However, as mentioned previously, the array index need not be
  11643.              a simple constant, as in the "1, 2, 3" case above. To ini-
  11644.              tialize all of the elements in the array to the value 42, a
  11645.              for loop can be used, along with an integer index:
  11646.  
  11647.                 #include <max.mh>
  11648.  
  11649.                 int main()
  11650.                 {
  11651.                   array [1..100] of int: my_ints;
  11652.                   int: i;
  11653.  
  11654.                   // This 'for' loop increments 'i' from 1
  11655.                   // to 100.
  11656.  
  11657.                   for (i := 1; i <= 100; i := i + 1)
  11658.                   {
  11659.                        // Set each integer to 42.
  11660.  
  11661.                        my_ints[i] := 42;
  11662.                   }
  11663.  
  11664.                   return 0;
  11665.  
  11666.  
  11667.  
  11668.              11. MEX Language Tutorial                                 209
  11669.  
  11670.                 }
  11671.  
  11672.              A more complicated expression can also be used as an index.
  11673.              For example, to initialize only even-numbered data objects:
  11674.  
  11675.                 #include <max.mh>
  11676.  
  11677.                 int main()
  11678.                 {
  11679.                   array [1..100] of int: my_ints;
  11680.                   int: i;
  11681.  
  11682.                   // Note that 'i' goes from 1 to 50, since we
  11683.                   // are multiplying it by 2 below.
  11684.  
  11685.                   for (i := 1; i <= 50; i := i + 1)
  11686.                   {
  11687.                        // Initialize data objects indexed by i*2,
  11688.                        // which will result in indices of 2, 4,
  11689.                        // 6, 8, and so on.
  11690.  
  11691.                        my_ints[i*2] := 42;
  11692.                   }
  11693.  
  11694.                   return 0;
  11695.                 }
  11696.  
  11697.              Similarly, the values in arrays can also be manipulated in
  11698.              other expressions. The following example creates an array
  11699.              containing the powers of 2:
  11700.  
  11701.                 #include <max.mh>
  11702.  
  11703.                 int main()
  11704.                 {
  11705.                   array [1..8] of int: my_ints;
  11706.                   int: i;
  11707.  
  11708.                   for (i := 1; i <= 8; i := i + 1)
  11709.                   {
  11710.  
  11711.                        if (i = 1)
  11712.                             my_ints[1] := 1;
  11713.                        else
  11714.                             my_ints[i] := my_ints[i-1] * 2;
  11715.  
  11716.                        print("Array at ", i, " is ",
  11717.                              my_ints[i], '\n');
  11718.                   }
  11719.  
  11720.                   return 0;
  11721.                 }
  11722.  
  11723.  
  11724.  
  11725.              11. MEX Language Tutorial                                 210
  11726.  
  11727.              11.10.3. Arrays as Function Parameters
  11728.  
  11729.              This section describes how to pass the information contained
  11730.              in arrays to other functions.
  11731.  
  11732.  
  11733.              11.10.3.1. Fixed-Length Arrays
  11734.  
  11735.              To pass information in an array to a function, one possible
  11736.              option is to pass each element in the array as a separate ar-
  11737.              gument, as shown below:
  11738.  
  11739.                 array [1..100] of int: my_ints;
  11740.  
  11741.                 // initialize array
  11742.  
  11743.                 process_an_int(my_ints[1]);
  11744.  
  11745.              This example passes the first element of my_ints to the proc-
  11746.              ess_an_int function.
  11747.  
  11748.              However, the entire array can also be passed as a parameter
  11749.              in a function call. To do this:
  11750.  
  11751.              1. Ensure that the array types match. In the function proto-
  11752.                 type and definition, the array parameter type must be iden-
  11753.                 tical to the argument type that the caller provides in the
  11754.                 function call. For example, if passing an array called
  11755.                 "my_ints", and if my_ints has a type of "array [1..50] of
  11756.                 string," this exact type definition must also be included
  11757.                 in the function prototype and definition.
  11758.  
  11759.              2. Specify the name of the array variable when writing the
  11760.                 function call. Just include the name of the array variable
  11761.                 itself (without using the array operator).
  11762.  
  11763.              For example:
  11764.  
  11765.                 #include <max.mh>
  11766.  
  11767.                 void handle_ints(array [1..50] of int: my_array);
  11768.  
  11769.                 int main()
  11770.                 {
  11771.                   // Note that the type of the my_ints variable
  11772.                   // matches the type in the function prototype
  11773.                   // above.
  11774.  
  11775.                   array [1..50] of int: my_ints;
  11776.  
  11777.                   // initialize array here
  11778.  
  11779.                   handle_ints(my_ints);
  11780.  
  11781.  
  11782.  
  11783.              11. MEX Language Tutorial                                 211
  11784.  
  11785.                   return 0;
  11786.                 }
  11787.  
  11788.                 void handle_ints(array [1..50] of int: my_array)
  11789.                 {
  11790.                   int: i;
  11791.  
  11792.                   // Now loop through all of the integers and
  11793.                   // display them.
  11794.  
  11795.                   for (i := 1; i <= 50; i := i + 1)
  11796.                        print("Int ", i, " is ", my_array[i], '\n');
  11797.                 }
  11798.  
  11799.              The handle_ints function takes the my_array parameter and
  11800.              displays the value of every integer in the array.
  11801.  
  11802.              Unlike other types, arrays are always passed by reference.
  11803.              Even if no ref qualifier is present in the parameter list,
  11804.              any changes that the called function makes to the array will
  11805.              also be reflected in the caller's copy of the array.
  11806.  
  11807.              This allows a called function to adjust certain values in an
  11808.              array with little or no impact on program performance:
  11809.  
  11810.                 #include <max.mh>
  11811.  
  11812.                 void adjust_ints(array [1..50] of int: my_ints);
  11813.  
  11814.                 int main()
  11815.                 {
  11816.                   array [1..50] of int: foo;
  11817.  
  11818.                   // Initialize the array and display foo[2]
  11819.  
  11820.                   foo[1] := 3;
  11821.                   foo[2] := 8;
  11822.                   foo[3] := 9;
  11823.  
  11824.                   print("foo #2 is ", foo[2], '\n');
  11825.  
  11826.                   // Call adjust_ints and redisplay foo[2]
  11827.  
  11828.                   adjust_ints(foo);
  11829.  
  11830.                   print("foo #2 is ", foo[2], '\n');
  11831.  
  11832.                   return 0;
  11833.                 }
  11834.  
  11835.                 void adjust_ints(array [1..50] of int: my_ints)
  11836.                 {
  11837.                   my_ints[2] := 4;
  11838.  
  11839.  
  11840.  
  11841.              11. MEX Language Tutorial                                 212
  11842.  
  11843.                 }
  11844.  
  11845.              This program will display:
  11846.  
  11847.                 foo #2 is 8
  11848.                 foo #2 is 4
  11849.  
  11850.  
  11851.              11.10.3.2. Variable-Length Arrays as Function Parameters
  11852.  
  11853.              One common approach when using arrays is to write separate
  11854.              functions to manipulate the contents of an array of a speci-
  11855.              fied type. Unfortunately, even though arrays containing the
  11856.              same type of object are used in many places, not all of these
  11857.              arrays are guaranteed to have the same bounds.
  11858.  
  11859.              For example, suppose that we have two arrays containing the
  11860.              average daily temperature for each day in February and March
  11861.              (respectively). The arrays would be declared like this:
  11862.  
  11863.                 array [1..28] of int: feb_temp;
  11864.                 array [1..30] of int: mar_temp;
  11865.  
  11866.              Now, suppose that we want to print out all of the tempera-
  11867.              tures for a given month. For our first attempt, we try creat-
  11868.              ing a function with the following prototype:
  11869.  
  11870.                 int print_temps(array [1..30] of int: month_temp);
  11871.  
  11872.              Unfortunately, even though we can call
  11873.              "print_temps(mar_temp)" using the above prototype, we get a
  11874.              MEX compile-time error if we try to call
  11875.              "print_temps(feb_temp)."
  11876.  
  11877.              This error occurs because the bounds of the declared array do
  11878.              not match the bounds of the array specified in the function
  11879.              prototype. Separate print_temps functions could be created
  11880.              with different array bounds, but this would lead to unneces-
  11881.              sary duplication of program code.
  11882.  
  11883.              To solve the problem in an elegant manner, MEX permits vari-
  11884.              able-length arrays in function prototypes and function defi-
  11885.              nitions. The lower bound for the array must still be speci-
  11886.              fied, and the lower bound must still match between the argu-
  11887.              ment and the parameter. However, the upper bound can be omit-
  11888.              ted. This tells MEX that the called function can accept an
  11889.              array of any length.
  11890.  
  11891.              A variable-length array can be declared as shown below. Note
  11892.              that this style of array declaration is only valid in func-
  11893.              tion parameter lists and prototypes:
  11894.  
  11895.                 array [lower .. ] of type: varname
  11896.  
  11897.  
  11898.  
  11899.              11. MEX Language Tutorial                                 213
  11900.  
  11901.  
  11902.              The only difference between this format and the standard ar-
  11903.              ray declaration format is the absence of upper. Aside from
  11904.              this omission, the components of the two declaration formats
  11905.              are identical.
  11906.  
  11907.              Even though the upper bound can be omitted in the called
  11908.              function, it is still the called function's responsibility to
  11909.              ensure that the array is only accessed within a valid set of
  11910.              bounds. The array referenced by the parameter is the same ar-
  11911.              ray as was declared in the calling function. Consequently, if
  11912.              the original array had bounds of 5 to 10, the called function
  11913.              must not use an index outside of the 5 through 10 range when
  11914.              accessing the parameter. The conventional way to deal with
  11915.              this problem is to have the calling function pass an extra
  11916.              argument that indicates the bounds of the array.
  11917.  
  11918.              The following example shows how to use variable-length arrays
  11919.              to solve the "array of temperatures" problem discussed above:
  11920.  
  11921.                 #include <max.mh>
  11922.  
  11923.                 void print_temps(int: days,
  11924.                                  array [1..] of int: temps);
  11925.  
  11926.                 int main()
  11927.                 {
  11928.                   array [1..28] of int: feb_temp;
  11929.                   array [1..30] of int: mar_temp;
  11930.  
  11931.                   // Initialize the February array
  11932.  
  11933.                   feb_temp[1] := -15;
  11934.                   feb_temp[2] := -13;
  11935.                   // and so on
  11936.  
  11937.                   // Initialize the March array
  11938.  
  11939.                   mar_temp[1] := -3;
  11940.                   mar_temp[2] := 2;
  11941.                   // and so on
  11942.  
  11943.                   // Now print them both out:
  11944.  
  11945.                   print_temps(28, feb_temp);
  11946.                   print_temps(30, mar_temp);
  11947.                   return 0;
  11948.                 }
  11949.  
  11950.                 void print_temps(int: days, array [1..] of int: temps)
  11951.                 {
  11952.                   int: i;
  11953.  
  11954.  
  11955.  
  11956.              11. MEX Language Tutorial                                 214
  11957.  
  11958.                   // Loop through all of the days in the array,
  11959.                   // as specified by the 'days' parameter, and
  11960.                   // print out the temperature for that day.
  11961.  
  11962.                   for (i := 1; i <= days; i := i + 1)
  11963.                   {
  11964.                        print("Temperature for day ", i, " is ",
  11965.                              temps[i], '\n');
  11966.                   }
  11967.                 }
  11968.  
  11969.  
  11970.              11.11. Structures
  11971.  
  11972.              When a function must manage a large amount of information, it
  11973.              is often helpful to group that information together in a
  11974.              logical manner. For example, to design an electronic address
  11975.              book, one possible (but clumsy) approach is to declare a
  11976.              separate variable for each item in the address book, like
  11977.              this:
  11978.  
  11979.                 string: name;
  11980.                 string: address;
  11981.                 string: city;
  11982.                 string: province;
  11983.  
  11984.              Then, every time a data record needed to be read in or writ-
  11985.              ten out, each variable could be manipulated separately. Simi-
  11986.              larly, every time a function needed to access information in
  11987.              the address record, each variable would need to be passed as
  11988.              a separate parameter.
  11989.  
  11990.              However, MEX provides a much easier way to group variables.
  11991.              The structure is an aggregate data type that acts as a
  11992.              "container" for other variables.
  11993.  
  11994.              Structure variables (which are simply variables that are de-
  11995.              clared of the structure type) can then be manipulated, as-
  11996.              signed and copied as a single data object. These actions act
  11997.              upon all of the fields contained within the structure. If de-
  11998.              sired, the fields within the structure can also be accessed
  11999.              individually.
  12000.  
  12001.              Unlike arrays, structures can contain objects of different
  12002.              data types. Because of this, there is no way to specify an
  12003.              integer "index" to obtain a particular data object that is
  12004.              contained within the structure. (However, one can construct
  12005.              an array of structures; see section 11.11.4 below for more
  12006.              information.)
  12007.  
  12008.  
  12009.  
  12010.              11. MEX Language Tutorial                                 215
  12011.  
  12012.              11.11.1. Defining Structure Types
  12013.  
  12014.              Before a structure variable can be declared, the format of
  12015.              the structure itself must be defined. For example, in the ad-
  12016.              dress book example, we would need to tell the compiler that
  12017.              an "address book structure" contained the four string vari-
  12018.              ables mentioned above.
  12019.  
  12020.              The definition of a structure type looks like this:
  12021.  
  12022.                 struct tag
  12023.                 {
  12024.                   field-decl-list
  12025.                 };
  12026.  
  12027.              Structure definitions must be placed at the top of the source
  12028.              file, outside of any function definition.
  12029.  
  12030.              tag is an arbitrary, user-defined "tag" for the structure.
  12031.              The tag identifies a particular structure type and its con-
  12032.              tents. A program can use many different structure types at
  12033.              the same time ---such as both an address book structure and a
  12034.              phone book structure, as could be envisaged for our example
  12035.              above ---so the tag is needed to differentiate between dif-
  12036.              ferent structure types.
  12037.  
  12038.              The tag can be set to any arbitrary name, as long as the name
  12039.              is unique among other functions, global variables and struc-
  12040.              tures. The tag is used later when declaring variables of the
  12041.              specified structure type. The tag name must also abide by the
  12042.              usual variable-naming conventions:
  12043.  
  12044.              *  The name must be from 1 to 32 characters long.
  12045.  
  12046.              *  The name is case-sensitive. This means that "delta,"
  12047.                 "Delta," "DELTA," and "DeLtA" refer to four distinct ob-
  12048.                 jects.
  12049.  
  12050.              *  Names can include letters and underscores. Names can also
  12051.                 include digits, except in the first character of the name.
  12052.                 (This means that "top10" is a valid name, whereas "7up" is
  12053.                 not.)
  12054.  
  12055.              The field-decl-list contains a number of field definitions. A
  12056.              field is simply a data object contained within the structure.
  12057.              In our example at the beginning of the section, the name and
  12058.              address variables are fields in the address book structure.
  12059.  
  12060.              A single semicolon must follow the closing brace of the
  12061.              structure.
  12062.  
  12063.              The field-decl-list looks exactly like a variable declaration
  12064.              block at the beginning of a function. For example, if we were
  12065.  
  12066.  
  12067.  
  12068.              11. MEX Language Tutorial                                 216
  12069.  
  12070.              to give our address book structure a tag of "abook," the
  12071.              definition would look like this:
  12072.  
  12073.                 struct abook
  12074.                 {
  12075.                   string: name;
  12076.                   string: address;
  12077.                   string: city;
  12078.                   string: province;
  12079.                 };
  12080.  
  12081.              This structure definition has a tag of abook, and the struc-
  12082.              ture contains the fields name, address, city and province.
  12083.  
  12084.              However, as with variable declaration blocks, the fields in a
  12085.              structure need not all be of the same type. Our address book
  12086.              could be expanded to include more useful information, as
  12087.              shown below:
  12088.  
  12089.                 struct abook
  12090.                 {
  12091.                   string: firstname;  // "John"
  12092.                   char: initial;      // 'Q'
  12093.                   string: lastname;        // "Public"
  12094.  
  12095.                   int: house_number;  // 777
  12096.                   string: street;          // Downing St.
  12097.                   string: city;       // Kingston
  12098.                   string: province;        // Ontario
  12099.                 };
  12100.  
  12101.              This structure contains a number of string variables as be-
  12102.              fore, but it also contains an int and a char to store indi-
  12103.              vidual pieces of the address information.
  12104.  
  12105.              This structure type definition will be used by several exam-
  12106.              ples in the following sections. This type definition should
  12107.              be included in any source file that uses the abook structure.
  12108.  
  12109.  
  12110.              11.11.2. Declaring Structure Variables
  12111.  
  12112.              Once a structure type has been defined, variables of that
  12113.              structure type can be created. Just like a normal int (or
  12114.              other variable type), structure variable declarations are
  12115.              placed in the variable declaration block at the beginning of
  12116.              a function.
  12117.  
  12118.              A structure variable declaration looks like this:
  12119.  
  12120.                 struct tag varname;
  12121.  
  12122.  
  12123.  
  12124.              11. MEX Language Tutorial                                 217
  12125.  
  12126.              The tag refers to a structure tag that was previously de-
  12127.              clared in a structure type definition.
  12128.  
  12129.              varname is the name of the structure variable to be declared.
  12130.  
  12131.              Given our address book example, suppose that we wanted to
  12132.              create two entries in the address book. We could then declare
  12133.              two structure variables as follows:
  12134.  
  12135.                 struct abook: john;
  12136.                 struct abook: steve;
  12137.  
  12138.              This would create variables called john and steve, each con-
  12139.              taining distinct copies of the fields in the address book
  12140.              structure.
  12141.  
  12142.  
  12143.              11.11.3. Using Structure Variables
  12144.  
  12145.              For the most part, structure variables can be manipulated
  12146.              like other data types. While it is obviously not possible to
  12147.              use arithmetic operators on entire structures (what would
  12148.              "steve + john" mean?), these structure variables can be as-
  12149.              signed, passed as parameters in function calls, and so on.
  12150.  
  12151.              In addition to the standard operators, the field selector op-
  12152.              erator ("." ---a period) is a special operator that can only
  12153.              be used with structures. This operator is used to directly
  12154.              access a single field contained within a structure.
  12155.  
  12156.              Within an expression, the field selector operator is used
  12157.              like this:
  12158.  
  12159.                 structvar . field
  12160.  
  12161.              structvar is the name of a previously-declared structure
  12162.              variable, such as "john" (from our previous example).
  12163.  
  12164.              Following the period ("."), the field is the name of one of
  12165.              the fields declared in the original structure definition,
  12166.              such as "firstname" or "street."
  12167.  
  12168.              By applying the field selector operator to a structure vari-
  12169.              able and a field name, single fields within the structure can
  12170.              be manipulated individually.
  12171.  
  12172.              The field selector operator is always used as part of an ex-
  12173.              pression. In other words, after applying the field selector
  12174.              operator to a structure variable and a field name, the result
  12175.              is always assigned to another variable, used as the target of
  12176.              an assignment, or included in some other expression.
  12177.  
  12178.  
  12179.  
  12180.              11. MEX Language Tutorial                                 218
  12181.  
  12182.              For example, given an address book structure named john, we
  12183.              can assign a value to one of its fields like this:
  12184.  
  12185.                 john.lastname := "Public";
  12186.  
  12187.              It may be useful to think of the structure operator as a way
  12188.              to select a certain field from a structure (which can then be
  12189.              used in the following operation).
  12190.  
  12191.              After using the field selector, the result is an object which
  12192.              has a type equivalent to the type of the field. With our ad-
  12193.              dress book example, if we had declared a structure variable
  12194.              called john, the object "john.firstname" has a type of
  12195.              string. This means that john.firstname can be manipulated
  12196.              just like any other string.
  12197.  
  12198.              In addition to assigning a string to john.lastname, as we did
  12199.              above, the following type of manipulation is also perfectly
  12200.              acceptable:
  12201.  
  12202.                 fullname := john.firstname + " " + john.lastname;
  12203.  
  12204.              This expression takes the firstname field (which is a string)
  12205.              from within the john structure, and it then uses the catena-
  12206.              tion operator to add a space, followed by the contents of
  12207.              john.lastname.
  12208.  
  12209.              The following sample program shows how values can be assigned
  12210.              to and retrieved from fields in a structure:
  12211.  
  12212.                 #include <max.mh>
  12213.  
  12214.                 struct abook
  12215.                 {
  12216.                   string: firstname;
  12217.                   char: initial;
  12218.                   string: lastname;
  12219.  
  12220.                   int: house_number;
  12221.                   string: street;
  12222.                   string: city;
  12223.                   string: province;
  12224.                 };
  12225.  
  12226.  
  12227.                 int main()
  12228.                 {
  12229.                   struct abook: john;
  12230.                   struct abook: steve;
  12231.  
  12232.                   john.firstname     := "John";
  12233.                   john.initial       := 'Q';
  12234.                   john.lastname      := "Public";
  12235.  
  12236.  
  12237.  
  12238.              11. MEX Language Tutorial                                 219
  12239.  
  12240.                   john.house_number  := 777;
  12241.                   john.street        := "Downing St";
  12242.                   john.city          := "Kingston";
  12243.                   john.province      := "Ontario";
  12244.  
  12245.                   steve.firstname    := "Steve";
  12246.                   steve.initial      := 'S';
  12247.                   steve.lastname     := "Smith";
  12248.                   steve.house_number := 5;
  12249.                   steve.street       := "Smith St";
  12250.                   steve.city         := "Smiths Falls";
  12251.                   steve.province     := "Ontario";
  12252.  
  12253.                   print("John's last name is ",john.lastname,'\n');
  12254.                   print("Steve's last name is ",steve.lastname,'\n');
  12255.  
  12256.                   return 0;
  12257.                 }
  12258.  
  12259.              This sample program should print:
  12260.  
  12261.                 John's last name is Public
  12262.                 Steve's last name is Smith
  12263.  
  12264.  
  12265.              11.11.4. Advanced Structure Definitions
  12266.  
  12267.              Structures can be used to store simple data types, such as
  12268.              int, char, string and long, but structures can also be used
  12269.              to store arrays and even nested copies of other structures.
  12270.  
  12271.              Structures containing other structures or arrays are declared
  12272.              in the same manner as less-complicated structures. In the
  12273.              case of structures containing structures, as long as the
  12274.              "child" structure (to be included within the "parent" struc-
  12275.              ture) is defined at an earlier point in the source file
  12276.              (relative to the parent definition), the structure definition
  12277.              can be written as one might expect:
  12278.  
  12279.                 struct date
  12280.                 {
  12281.                   int: year, month, day;
  12282.                 };
  12283.  
  12284.                 struct addressbook2
  12285.                 {
  12286.                   string: name;
  12287.                   struct date: date_entered;
  12288.                   struct date: date_updated;
  12289.                   array [1..2] of string: phone;
  12290.                 };
  12291.  
  12292.  
  12293.  
  12294.              11. MEX Language Tutorial                                 220
  12295.  
  12296.              This example uses a child structure, date, contained within
  12297.              the parent structure, addressbook2. The parent structure con-
  12298.              tains two copies of the date structure, called date_entered
  12299.              and date_updated. It also includes an array of strings for
  12300.              storing data and FAX phone numbers.
  12301.  
  12302.              The structure member operator (".") and array operators ("["
  12303.              and "]") can be combined in a logical manner to access the
  12304.              fields within these structures.
  12305.  
  12306.              The address book structure from above can be declared and
  12307.              used like this:
  12308.  
  12309.                 struct addressbook2: john;
  12310.  
  12311.                 john.name := "John Q. Public";   // standard field
  12312.  
  12313.                 john.date_entered.year  := 1995; // nested field
  12314.                 john.date_entered.month := 6;    // nested field
  12315.                 john.date_entered.day   := 18;   // nested field
  12316.  
  12317.                 john.date_updated.year  := 1995; // nested field
  12318.                 john.date_updated.year  := 7;    // nested field
  12319.                 john.date_updated.day   := 14;   // nested field
  12320.  
  12321.                 john.phone[1] := "+1-613-389-8315"; // array field
  12322.                 john.phone[2] := "+1-613-634-3058"; // array field
  12323.  
  12324.              Other advanced constructs can also be used. For example, an
  12325.              array of structures can be declared to hold an entire address
  12326.              catalog. Fields within the structures can then be accessed
  12327.              like this, assuming the addressbook2 definition from above:
  12328.  
  12329.                 array [1..10] of struct addressbook2: book;
  12330.  
  12331.                 book[1].name := "Steve S. Smith";
  12332.                 book[1].date_entered.year := 1995;
  12333.                 book[1].phone[1] := "+1-613-634-3058";
  12334.                 // etc.
  12335.  
  12336.                 book[2].name := "John Q. Public";
  12337.                 book[2].date_entered.year := 1995;
  12338.                 book[2].date_updated.month := 6;
  12339.                 // etc.
  12340.  
  12341.              This makes it possible to perform the same operations on many
  12342.              structures, which has many applications in data processing
  12343.              programs. For example, given the address book definition from
  12344.              above, the following program segment could be used to print
  12345.              out the names of everyone in the address book:
  12346.  
  12347.                 int: idx;
  12348.  
  12349.  
  12350.  
  12351.              11. MEX Language Tutorial                                 221
  12352.  
  12353.                 for (idx := 1; idx <= 10; idx := idx + 1)
  12354.                 {
  12355.                   // If the name in this address book record is
  12356.                   // not empty, print it out.
  12357.  
  12358.                   if (book[idx].name <> "")
  12359.                        print("Name is ", book[idx].name, '\n');
  12360.                 }
  12361.  
  12362.              11.11.5. Structures as Function Parameters
  12363.  
  12364.              Structures can also be passed as parameters to functions.
  12365.              Just like other variable types, the contents of the struc-
  12366.              tures can be accessed from within the called function using
  12367.              standard syntax.
  12368.  
  12369.              In the function prototype and function definition, simply in-
  12370.              clude the variable type and name in the parameter list. (For
  12371.              example, "struct addressbook: mybook" could be added to the
  12372.              parameter list to specify an address book structure.)
  12373.  
  12374.              Next, when writing the function call, just include the name
  12375.              of the structure variable to be passed to the caller. For ex-
  12376.              ample:
  12377.  
  12378.                 #include <max.mh>
  12379.  
  12380.                 struct date
  12381.                 {
  12382.                   int: year, month, day;
  12383.                 };
  12384.  
  12385.                 // Prototype for the function declared below.
  12386.  
  12387.                 void showdate(struct date: d);
  12388.  
  12389.                 int main()
  12390.                 {
  12391.                   struct date: d1, d2;
  12392.  
  12393.                   // Initialize dates
  12394.  
  12395.                   d1.year := 1995;
  12396.                   d1.month := 7;
  12397.                   d1.day := 1;
  12398.  
  12399.                   d2.year := 1994;
  12400.                   d2.month := 3;
  12401.                   d2.day := 24;
  12402.  
  12403.                   // Display them to the user
  12404.  
  12405.                   showdate(d1);
  12406.  
  12407.  
  12408.  
  12409.              11. MEX Language Tutorial                                 222
  12410.  
  12411.                   showdate(d2);
  12412.  
  12413.                   return 0;
  12414.                 }
  12415.  
  12416.                 void showdate(struct date: d)
  12417.                 {
  12418.                   print(d.month, '/', d.day, '/', d.year, '\n');
  12419.                 }
  12420.  
  12421.              Upon running the above program, the following is displayed:
  12422.  
  12423.                 7/1/1995
  12424.                 3/24/1994
  12425.  
  12426.              However, like arrays, structures are always passed by refer-
  12427.              ence, regardless of whether or not the ref qualifier is used.
  12428.              This means that the called function will always be able to
  12429.              modify the contents of the structure passed in by the parent.
  12430.              For example:
  12431.  
  12432.                 #include <max.mh>
  12433.  
  12434.                 struct date
  12435.                 {
  12436.                   int: year, month, day;
  12437.                 };
  12438.  
  12439.                 void changeit(ref struct date: d)
  12440.                 {
  12441.                   d.year := 1993;
  12442.                 }
  12443.  
  12444.                 int main()
  12445.                 {
  12446.                   struct date: d;
  12447.  
  12448.                   d.year := 1995;
  12449.                   d.month := 4;
  12450.                   d.day := 16;
  12451.  
  12452.                   print(d.month, '/', d.day, '/', d.year, '\n');
  12453.                   changeit(d);
  12454.                   print(d.month, '/', d.day, '/', d.year, '\n');
  12455.  
  12456.                   return 0;
  12457.                 }
  12458.  
  12459.              This sample program will print:
  12460.  
  12461.                 4/16/1995
  12462.                 4/16/1993
  12463.  
  12464.  
  12465.  
  12466.              11. MEX Language Tutorial                                 223
  12467.  
  12468.              11.12. Casts
  12469.  
  12470.              A cast is an explicit instruction to the MEX compiler to con-
  12471.              vert a data object from one type to another. Casts are not
  12472.              required for most MEX programs, but they are useful in some
  12473.              situations.
  12474.  
  12475.              A cast is used within an expression like this:
  12476.  
  12477.                  (type) argument
  12478.  
  12479.              argument is the expression or object that is to be converted.
  12480.  
  12481.              type is the type to which argument is to be converted. MEX
  12482.              currently only allows programs to cast to or from the char,
  12483.              int, and long types.
  12484.  
  12485.              For example, the following code segment converts a char so
  12486.              that it can be assigned to a long:
  12487.  
  12488.                 char: c;
  12489.                 long: l;
  12490.  
  12491.                 c := 'A';
  12492.  
  12493.                 l := (long)c;         // l now contains 65, the ASCII
  12494.                                  // value of 'c'.
  12495.  
  12496.              In many cases, casting is not necessary. In the example
  12497.              above, MEX would perform an implicit type conversion anyway
  12498.              if the cast were not specified. The following line would have
  12499.              exactly the same effect:
  12500.  
  12501.                 l := c;          // perform implicit conversion
  12502.                                  // from char to long.
  12503.  
  12504.              However, casts are sometimes used when calling the print
  12505.              function to display output of a certain type. The print func-
  12506.              tion is type-sensitive, meaning that it produces different
  12507.              forms of output depending on the type of data object that is
  12508.              passed to it.
  12509.  
  12510.              For example, if we have the following code:
  12511.  
  12512.                 #include <max.mh>
  12513.  
  12514.                 int main()
  12515.                 {
  12516.                   char: c;
  12517.                   int: i;
  12518.                   long: l;
  12519.  
  12520.                   c := 65;
  12521.  
  12522.  
  12523.  
  12524.              11. MEX Language Tutorial                                 224
  12525.  
  12526.                   i := 65;
  12527.                   l := 65;
  12528.  
  12529.                   print(c, '\n');
  12530.                   print(i, '\n');
  12531.                   print(l, '\n');
  12532.  
  12533.                   return 0;
  12534.                 }
  12535.  
  12536.              The program will display the following output:
  12537.  
  12538.                 A
  12539.                 65
  12540.                 65
  12541.  
  12542.              The number 65 is the ASCII value of the letter `A', and since
  12543.              print knows that it is displaying a character, the first line
  12544.              in the output is the character representation of c.
  12545.  
  12546.              Likewise, print knows when it is displaying integers and long
  12547.              integers, so it formats the output appropriately.
  12548.  
  12549.              Casting is useful when you have an object of one data type
  12550.              but wish it to be displayed as an object of another type.
  12551.  
  12552.              For example, suppose that we actually wanted our program to
  12553.              display the ASCII value of c. We could then rewrite that one
  12554.              line like this:
  12555.  
  12556.                 print( (int)c, '\n' );
  12557.  
  12558.              which would produce the desired output of "65." The cast con-
  12559.              verts the character to an integer, so when print goes to dis-
  12560.              play the object, it applies the standard integer formatting
  12561.              rules.
  12562.  
  12563.              Likewise, casts can be useful when dealing with signed and
  12564.              unsigned integers. MEX stores negative numbers using the
  12565.              standard two's complement notation; this means that "-1" is
  12566.              represented (in a 16-bit int) as 65535; "-2" is represented
  12567.              as 65534; and so on.
  12568.  
  12569.              If your program reads in a value as an unsigned integer but
  12570.              wishes to display the signed representation of that number,
  12571.              the following code can do the job:
  12572.  
  12573.                 #include <max.mh>
  12574.  
  12575.                 int main()
  12576.                 {
  12577.                   unsigned int: ui;
  12578.  
  12579.  
  12580.  
  12581.              11. MEX Language Tutorial                                 225
  12582.  
  12583.                   // Code to read the integer would go here. For this
  12584.                   // example, we just assign an unsigned value to the
  12585.                   // 'ui' variable.
  12586.  
  12587.                   ui := 65532;
  12588.  
  12589.                   print("Unsigned is ", ui, '\n');
  12590.                   print("  Signed is ", (int)ui, '\n');
  12591.  
  12592.                   return 0;
  12593.                 }
  12594.  
  12595.              This code will display:
  12596.  
  12597.                 Unsigned is 65532
  12598.                   Signed is -4
  12599.  
  12600.              Likewise, a similar cast can be used to convert a negative
  12601.              signed number into the standard two's-complement (unsigned)
  12602.              representation.
  12603.  
  12604.  
  12605.              11.13. Further Explorations in MEX
  12606.  
  12607.              This completes the MEX language tutorial. While far from a
  12608.              comprehensive programming design manual, this section should
  12609.              have given you an overview of the capabilities of the MEX
  12610.              language, and it should have also given you some ideas for
  12611.              writing programs of your own.
  12612.  
  12613.              From here, the best thing to do is to try writing some MEX
  12614.              programs. After you feel comfortable with the basics of the
  12615.              MEX language, also have a look at section 13 later in this
  12616.              document.
  12617.  
  12618.              In that section, a number of helpful interfacing tips are
  12619.              presented for writing MEX programs that interface with the
  12620.              internal Maximus functions and data structures. Since the
  12621.              goal of writing MEX programs is typically to extend the func-
  12622.              tionality of Maximus in some way, section 13 is a valuable
  12623.              resource.
  12624.  
  12625.              Also, section 15 will also prove to be useful for first-time
  12626.              MEX programmers. That section describes how to use all of the
  12627.              functions in the MEX run-time library; you will probably find
  12628.              that many of these functions come in handy when writing your
  12629.              own MEX programs, so it pays to know what is in the run-time
  12630.              library before you start writing.
  12631.  
  12632.              Good luck in the world of MEX programming!
  12633.  
  12634.  
  12635.  
  12636.  
  12637.  
  12638.  
  12639.  
  12640.  
  12641.                                        12. MEX for C and Pascal Programmers
  12642.  
  12643.              This section serves as a brief summary of the MEX language
  12644.              for intermediate programmers. A familiarity is assumed with
  12645.              either the C or the Pascal programming language.
  12646.  
  12647.              This section is very much a "whirlwind tour" of the concepts
  12648.              used in the MEX language. The details given below are proba-
  12649.              bly not enough to allow a C or Pascal developer to start pro-
  12650.              gramming in MEX right away.
  12651.  
  12652.              Instead, this section should be used as a list of key MEX
  12653.              features that are similar to or different from other lan-
  12654.              guages. Much more detailed explanations of these key concepts
  12655.              can be found in section 11.
  12656.  
  12657.  
  12658.              12.1. Comments
  12659.  
  12660.              A comment is started by the two-character sequence "//" and
  12661.              continues until the end of the line. This concept is borrowed
  12662.              from C++ (and indirectly from BCPL).
  12663.  
  12664.  
  12665.              12.2. Include Files
  12666.  
  12667.              MEX borrows the "include file" concept from the C language.
  12668.              The #include directive instructs MEX to read in the named
  12669.              file and process it as if it were included directly in the
  12670.              source file.
  12671.  
  12672.              The following line must be present at the top of each MEX
  12673.              file designed to interface with Maximus:
  12674.  
  12675.                 #include <max.mh>
  12676.  
  12677.  
  12678.              12.3. Blocks
  12679.  
  12680.              For denoting logical blocks within a function, MEX uses the
  12681.              "{" and "}" characters, as in C. These are equivalent to the
  12682.              "begin" and "end" keywords in Pascal.
  12683.  
  12684.  
  12685.              12.4. Function Definitions
  12686.  
  12687.              As in C, a subprogram in MEX is always called a function. A
  12688.              "procedure" is equivalent to a function that returns void.
  12689.  
  12690.              A function definition looks like this:
  12691.  
  12692.  
  12693.  
  12694.              12. MEX for C and Pascal Programmers                      228
  12695.  
  12696.                 returntype name (param-list)
  12697.                 {
  12698.                   // body goes here
  12699.                 }
  12700.  
  12701.              where returntype is the return type of the function, name is
  12702.              the name of the function to be defined, and param-list is a
  12703.              comma-delimited list of function parameters.
  12704.  
  12705.  
  12706.              12.5. Types
  12707.  
  12708.              MEX supports the following types: char, int, long, string,
  12709.              struct, array, and void. char, int, and long are integral
  12710.              data types. struct and array are aggregate data types that
  12711.              contain many data objects. void is a special data type used
  12712.              only for function return values and ref void function parame-
  12713.              ters.
  12714.  
  12715.              Both signed and unsigned versions of the three integral types
  12716.              can be declared. Without an explicit signed or unsigned type
  12717.              qualifier, the char type is unsigned, while both int and long
  12718.              are signed by default.
  12719.  
  12720.              The char, int, long, struct and void types are borrowed from
  12721.              C.
  12722.  
  12723.              The array type is borrowed from Pascal.
  12724.  
  12725.              The string type is borrowed from BASIC.
  12726.  
  12727.  
  12728.              12.6. Variable Declarations
  12729.  
  12730.              A single variable declaration looks like this:
  12731.  
  12732.                 type: name-list;
  12733.  
  12734.              type can be one of the standard type names, including char,
  12735.              int, long, and string. type can also be an array type ("array
  12736.              [lower .. upper] of type") or a structure type ("struct
  12737.              tag"). The type name is always followed by a colon (":").
  12738.  
  12739.              name is a comma-delimited list describing the names of the
  12740.              variables to be declared. The variable name must abide by
  12741.              these conventions:
  12742.  
  12743.              *  The name must be from 1 to 32 characters long.
  12744.  
  12745.              *  The name is case-sensitive. This means that "delta,"
  12746.                 "Delta," "DELTA," and "DeLtA" refer to four distinct ob-
  12747.                 jects.
  12748.  
  12749.  
  12750.  
  12751.              12. MEX for C and Pascal Programmers                      229
  12752.  
  12753.              *  Names can include letters and underscores. Names can also
  12754.                 include digits, except in the first character of the name.
  12755.                 (This means that "top10" is a valid name, whereas "7up" is
  12756.                 not.)
  12757.  
  12758.              The variable declaration syntax is a mix of both C and Pascal
  12759.              declaration styles. Multiple variables declarations can be
  12760.              placed in a block after any opening brace in a function. No
  12761.              keywords are required to define the start or end of a vari-
  12762.              able declaration block; the compiler recognizes the declara-
  12763.              tions by context.
  12764.  
  12765.              A sample function that declares two strings and an integer is
  12766.              given below:
  12767.  
  12768.                 void myfunc()
  12769.                 {
  12770.                   string: str1, str2;
  12771.                   int: myint;
  12772.  
  12773.                   // function code goes here
  12774.                 }
  12775.  
  12776.              12.7. Function Prototypes
  12777.  
  12778.              Before a function may be called, a prototype must be declared
  12779.              that lists the function return value, name, and parameter
  12780.              list. This concept is similar to the C++ "prototype" and the
  12781.              Pascal "forward declaration." (However, if the function is
  12782.              defined at a point in the same source file above the call to
  12783.              that function, no prototype is required.)
  12784.  
  12785.              A function prototype looks just like a function definition,
  12786.              except that the "{" and "}" of the function body are replaced
  12787.              by a single semicolon (";").
  12788.  
  12789.  
  12790.              12.8. Function Return Values
  12791.  
  12792.              As in C, values are returned by functions using the return
  12793.              keyword. This differs from Pascal where the function return
  12794.              value is set by "assigning" a value to the name of the func-
  12795.              tion.
  12796.  
  12797.  
  12798.              12.9. Strings
  12799.  
  12800.              MEX supports dynamic strings, as in BASIC. When declaring a
  12801.              string, no explicit string length need be defined. Similarly,
  12802.              strings can be catenated, assigned, and otherwise manipulated
  12803.              without worrying about the length of the string.
  12804.  
  12805.  
  12806.  
  12807.              12. MEX for C and Pascal Programmers                      230
  12808.  
  12809.              Individual characters can be retrieved from (and inserted
  12810.              into) a string using the "str [ idx ]" operator, where str is
  12811.              a string variable and idx is an integer specifying the char-
  12812.              acter number to be modified, where an idx of 1 represents the
  12813.              first character in the string.
  12814.  
  12815.              The length of a string can be determined using the strlen
  12816.              function in the MEX run-time library. A number of other
  12817.              string-processing functions can also be found in the run-time
  12818.              library.
  12819.  
  12820.  
  12821.              12.10. Compound Statements
  12822.  
  12823.              MEX borrows the concept of compound statements from C. At any
  12824.              point in the language where a single statement is accepted, a
  12825.              group of n statements (or a compound statement) can be speci-
  12826.              fied as shown below:
  12827.  
  12828.                 {
  12829.                   stmt1;
  12830.                   stmt2;
  12831.                   // ...
  12832.                   stmtN;
  12833.                 }
  12834.  
  12835.              A compound statement begins with a left brace and ends with a
  12836.              right brace. Any number of statements can be contained. Com-
  12837.              pound statements can be nested.
  12838.  
  12839.  
  12840.              12.11. Arithmetic, Relational and Logical Operators
  12841.  
  12842.              MEX borrows concepts from both C and Pascal in this area.
  12843.  
  12844.              The assignment and equality operators are borrowed from Pas-
  12845.              cal. To assign a value to a variable, use the ":=" operator.
  12846.              To test if two variables are equal, use the "=" operator.
  12847.  
  12848.              The equality operator can operate upon all data types except
  12849.              array, struct and void.
  12850.  
  12851.              The assignment operator can operate upon all data types ex-
  12852.              cept array and void.
  12853.  
  12854.              The other arithmetic, relational and logical operators can
  12855.              operate only on the three integral data types, char, int and
  12856.              long. The "+" operator can also be used to catenate strings.
  12857.  
  12858.  
  12859.  
  12860.              12. MEX for C and Pascal Programmers                      231
  12861.  
  12862.              12.12. The for Statement
  12863.  
  12864.              MEX borrows the syntax for the for statement from the C lan-
  12865.              guage. The syntax is:
  12866.  
  12867.                 for (init-expr; test-expr; post-expr)
  12868.                   statement
  12869.  
  12870.              init-expr is evaluated only once (before any other part of
  12871.              the loop is executed).
  12872.  
  12873.              test-expr is evaluated every time the loop is executed, be-
  12874.              fore the first statement in the loop body is processed. The
  12875.              loop exits when test-expr equals zero.
  12876.  
  12877.              post-expr is evaluated after every iteration of the loop.
  12878.  
  12879.              statement is the statement (or compound block) that is per-
  12880.              formed every time the loop is executed.
  12881.  
  12882.  
  12883.              12.13. Arrays
  12884.  
  12885.              MEX uses a Pascal-like syntax for declaring arrays:
  12886.  
  12887.                 array [lower .. upper] of type: varname;
  12888.  
  12889.              lower is the lower bound of the array. This value must be an
  12890.              integer.
  12891.  
  12892.              upper is the upper bound of the array. This value must be an
  12893.              integer.
  12894.  
  12895.              type is the base type used for the data objects within the
  12896.              array.
  12897.  
  12898.              varname is the name of the variable to be declared.
  12899.  
  12900.              Data objects within an array can be accessed using the stan-
  12901.              dard array operator notation ("[" and "]"). The index value
  12902.              specified within must be of an integral type: either char,
  12903.              int, or long.
  12904.  
  12905.  
  12906.              12.14. Pointers
  12907.  
  12908.              MEX does not support pointer variables.
  12909.  
  12910.  
  12911.  
  12912.              12. MEX for C and Pascal Programmers                      232
  12913.  
  12914.              12.15. Pass-By-Reference Arguments
  12915.  
  12916.              As in Pascal, arguments passed to a function can be passed by
  12917.              reference. This allows the called function to modify the
  12918.              value of the argument specified by the caller.
  12919.  
  12920.              To use a pass-by-reference argument, the ref keyword is in-
  12921.              cluded before the variable type in the function's parameter
  12922.              list, for both the function prototype and the function defi-
  12923.              nition.
  12924.  
  12925.  
  12926.              12.16. Variable-Length Arrays
  12927.  
  12928.              In a function parameter list, MEX allows the programmer to
  12929.              omit the upper bound for an array declaration. This allows
  12930.              functions to accept variable-length arrays:
  12931.  
  12932.                 int process_array(array [1..] of int: my_array,
  12933.                                   int: size_of_my_array)
  12934.                 {
  12935.                   // process my_array here
  12936.                 }
  12937.  
  12938.              12.17. Structures
  12939.  
  12940.              MEX uses the C syntax for declaring and defining structures.
  12941.              (Structures are conceptually similar to the Pascal "record"
  12942.              type.) Before using a structure, the structure type must be
  12943.              defined as shown below:
  12944.  
  12945.                 struct tag
  12946.                 {
  12947.                   decl-list
  12948.                 };
  12949.  
  12950.              tag is the tag name associated with this structure type.
  12951.  
  12952.              decl-list contains a block of declarations which define the
  12953.              objects contained within the structure. This decl-list is
  12954.              identical to a variable declaration block in terms of syntax.
  12955.  
  12956.              To declare a structure variable, the following syntax is
  12957.              used:
  12958.  
  12959.                 struct tag: varname;
  12960.  
  12961.              This declaration instantiates a structure of the previously-
  12962.              defined tag type, creating a structure variable with name
  12963.              varname.
  12964.  
  12965.              To access a field within a structure, the structure member
  12966.              operator (".") is used. For example, if the structure foo
  12967.  
  12968.  
  12969.  
  12970.              12. MEX for C and Pascal Programmers                      233
  12971.  
  12972.              contained a field called my_string (of type string), a value
  12973.              could be assigned to that field as follows:
  12974.  
  12975.                 foo.my_string := "String to go into the foo struct.";
  12976.  
  12977.              12.18. Run-Time Library Support
  12978.  
  12979.              MEX supports an extensive run-time library that performs ba-
  12980.              sic I/O tasks and data manipulation. The run-time library
  12981.              also includes numerous interfaces to internal Maximus func-
  12982.              tions.
  12983.  
  12984.  
  12985.  
  12986.  
  12987.  
  12988.  
  12989.  
  12990.  
  12991.                                            13. Interfacing MEX with Maximus
  12992.  
  12993.              This section describes various issues related to interfacing
  12994.              MEX programs with Maximus. While all MEX programs must be run
  12995.              under Maximus, this section concentrates on those programs
  12996.              that tie into special Maximus-specific features and func-
  12997.              tions.
  12998.  
  12999.  
  13000.              13.1. User Information
  13001.  
  13002.              Maximus creates a number of important data structures that
  13003.              can be accessed by a MEX program. Of these structures, the
  13004.              most important is the user structure. Maximus creates a
  13005.              global variable called usr which contains a copy of informa-
  13006.              tion about the current user.
  13007.  
  13008.              The usr variable is accessible to any MEX program that con-
  13009.              tains the "#include <max.mh>" line at the top of the source
  13010.              file.
  13011.  
  13012.              The usr structure contains everything that Maximus knows
  13013.              about the current user, including the user's name, privilege
  13014.              level, key settings, date of the user's last call, and more.
  13015.  
  13016.              In general, this structure can be read from or written to at
  13017.              will. For example, to display a personal greeting to the
  13018.              user:
  13019.  
  13020.                 print("Hello there, ", usr.name, ", how are you?\n");
  13021.  
  13022.              If the user was called Steve Smith, the above line would dis-
  13023.              play:
  13024.  
  13025.                 Hello there, Steve Smith, how are you?
  13026.  
  13027.              Similarly, other fields in the user structure can be accessed
  13028.              or displayed:
  13029.  
  13030.                 print("You come from ", usr.city, " and you have "
  13031.                       "these keys: ", usr.xkeys, '\n');
  13032.  
  13033.              If the user's city field was set to "Smith Falls," and if the
  13034.              user had keys 1, 2, and C, the following would be displayed:
  13035.  
  13036.                 You come from Smith Falls and you have these keys: 12C
  13037.  
  13038.              Most variables in the user record can also be modified. For
  13039.              example, the following line will give key "D" to the current
  13040.              user and adjust the user's privilege level to 40:
  13041.  
  13042.  
  13043.  
  13044.              13. Interfacing MEX with Maximus                          236
  13045.  
  13046.                 usr.xkeys := usr.xkeys + "D";
  13047.                 usr.priv := 40;
  13048.  
  13049.              Most of the other fields in the user file can be accessed in
  13050.              a similar manner. For example, the usr.ludate structure can
  13051.              be used to determine the date of the user's last call. From
  13052.              there, the stamp_to_long function could be used to convert
  13053.              that structure into a long, which could then be compared with
  13054.              the current date to determine how many seconds had elapsed
  13055.              since the user's last call.
  13056.  
  13057.              Section 15 contains a list of all global data structures and
  13058.              their contents, including all of the fields in the user
  13059.              structure.
  13060.  
  13061.  
  13062.              13.2. Message Area Information
  13063.  
  13064.              Maximus stores information about the current message area in
  13065.              two places: in a structure called marea, which contains
  13066.              static information about the area itself, and it also stores
  13067.              data in a secondary structure called msg, which contains in-
  13068.              formation about the status of the area and the user's current
  13069.              message.
  13070.  
  13071.              As before, these structures are defined in the max.mh include
  13072.              file.
  13073.  
  13074.              The following code is used to display the name of the current
  13075.              message area:
  13076.  
  13077.                 print("You are in the ", marea.name, " area.\n");
  13078.  
  13079.              Unlike the user structure, the information in the marea
  13080.              structure cannot be changed.
  13081.  
  13082.              The msg structure can also be used to display information
  13083.              about the area that is relevant to the user. For example, to
  13084.              display the user's current message:
  13085.  
  13086.                 print("You just read message #", msg.current, '\n');
  13087.  
  13088.              The msg structure also contains information on the number of
  13089.              messages in the area and the highest message number. The
  13090.              msg.current field can be adjusted to change the current mes-
  13091.              sage number, but the other fields must not be modified.
  13092.  
  13093.              As before, information on the formats of these structures can
  13094.              be found in section 15.
  13095.  
  13096.  
  13097.  
  13098.              13. Interfacing MEX with Maximus                          237
  13099.  
  13100.              13.3. File Area Information
  13101.  
  13102.              Similarly, information on the current file area can be found
  13103.              in the farea structure. Just like the marea structure, it
  13104.              must not be modified by MEX programs.
  13105.  
  13106.  
  13107.              13.4. Changing Message and File Areas
  13108.  
  13109.              The msg_area and file_area functions display a list of areas
  13110.              and prompt the user to select a new area. The msgareaselect
  13111.              and fileareaselect functions explicitly move the user to a
  13112.              specific message or file area.
  13113.  
  13114.  
  13115.              13.5. Displaying Output
  13116.  
  13117.              The standard MEX output function, print, is also used for
  13118.              most user-related display tasks. The full set of AVATAR color
  13119.              and cursor controls is available to MEX programs through this
  13120.              function.
  13121.  
  13122.              Some of the AVATAR sequences, such as simple color-changing
  13123.              commands, have already been predefined in max.mh. To use
  13124.              them, simply include the appropriate macro in your program
  13125.              source. For example, to display different parts of the text
  13126.              in white or green:
  13127.  
  13128.                 print(COL_WHITE "This text is displayed in white, "
  13129.                       "but this text " COL_GREEN "here" COL_WHITE
  13130.                       "is shown in green.\n");
  13131.  
  13132.              If the constant for the color you wish to use is not defined
  13133.              in one of the COL_* constants in max.mh, please see the AVA-
  13134.              TAR_ATTR sequence in the table below:
  13135.  
  13136.              Some of the other predefined AVATAR sequences are shown in
  13137.              Table 13.1:
  13138.  
  13139.              Table 13.1 AVATAR Control Sequences
  13140.  
  13141.               Command          Description
  13142.  
  13143.               AVATAR_ATTR      Set the current color based on the char-
  13144.                                acter following the AVATAR_ATTR sequence.
  13145.                                This character is encoded using the stan-
  13146.                                dard AVATAR color number, as given in
  13147.                                Appendix F. Do not forget to cast this
  13148.                                number to a char, as shown in the example
  13149.                                following this table.
  13150.               AVATAR_BLINK     The following text will blink. The blink-
  13151.                                ing attribute remains active until the
  13152.                                next AVATAR color command.
  13153.  
  13154.  
  13155.  
  13156.              13. Interfacing MEX with Maximus                          238
  13157.  
  13158.               AVATAR_UP        Move the cursor up by one line.
  13159.               AVATAR_DOWN      Move the cursor down by one line.
  13160.               AVATAR_LEFT      Move the cursor left by one column.
  13161.               AVATAR_RIGHT     Move the cursor right by one column.
  13162.               AVATAR_CLEOL     Clear from the cursor to the end of the
  13163.                                line, using the currently-selected at-
  13164.                                tribute.
  13165.               AVATAR_GOTO      Move the cursor to a specified location.
  13166.                                The next two characters following the
  13167.                                AVATAR_GOTO sequence must indicate the
  13168.                                row and column, respectively. (The two
  13169.                                following row/column values must be
  13170.                                casted to the char type. Casting is de-
  13171.                                scribed in section 11.12.)
  13172.               AVATAR_CLS       Clear the screen, move the cursor to row
  13173.                                1, column 1, and set the current color to
  13174.                                cyan.
  13175.  
  13176.  
  13177.              Based on the user's video setting, these AVATAR codes will be
  13178.              either sent as-is, translated into ANSI codes, or stripped
  13179.              from the display stream, depending on the user's graphics ca-
  13180.              pabilities. This translation is performed automatically by
  13181.              Maximus.
  13182.  
  13183.              As an example of graphics capabilities, this code clears the
  13184.              screen, moves the cursor to row 5, column 6, sets the color
  13185.              to light green, and then displays the text "Hello."
  13186.  
  13187.                 print(AVATAR_CLS AVATAR_GOTO, (char)5, (char)6,
  13188.                       COL_LGREEN "Hello.\n");
  13189.  
  13190.              To demonstrate the AVATAR_ATTR sequence, the following code
  13191.              changes the current color to light red on blue. By consulting
  13192.              the AVATAR color table in Appendix F, we see that light red
  13193.              on blue is color 28, so we proceed as follows:
  13194.  
  13195.                 print(COL_WHITE "This is a " AVATAR_ATTR, (char)28,
  13196.                       "gaudy" COL_WHITE " color.\n");
  13197.  
  13198.              13.6. Retrieving Input
  13199.  
  13200.              Maximus supports a number of functions which retrieve input
  13201.              from the user. Of these functions, the most commonly-used are
  13202.              input_str, input_list and input_ch.
  13203.  
  13204.              These functions use the same interface that Maximus itself
  13205.              uses for retrieving input. These functions can all display
  13206.              prompts and perform special actions depending on what the
  13207.              calling code requires:
  13208.  
  13209.              The input_str function is used to get either a single word or
  13210.              an entire string from the user.
  13211.  
  13212.  
  13213.  
  13214.              13. Interfacing MEX with Maximus                          239
  13215.  
  13216.              The input_list function prompts the user to enter a character
  13217.              from a specified list of choices. This is used internally for
  13218.              the "More [Y,n,=]?" prompt and also for most other questions
  13219.              that require single-character responses.
  13220.  
  13221.              The input_ch function obtains a single character from the
  13222.              user. This function can also interpret the "scan codes" used
  13223.              by terminal programs that support the "DoorWay" protocol.
  13224.  
  13225.              Also, the getch function is used to perform raw character in-
  13226.              put. It retrieves a character directly from the user, without
  13227.              going through the command stacking buffer or displaying any
  13228.              prompts.
  13229.  
  13230.  
  13231.              13.7. File I/O
  13232.  
  13233.              For manipulating files on disk, a number of run-time library
  13234.              functions come in handy. open, read, write, seek, tell and
  13235.              close are useful for reading, writing, and updating the con-
  13236.              tents of files. fileexists and filesize are used to determine
  13237.              general information about named files. And the filefind*
  13238.              functions can be used to expand wildcards to find files in a
  13239.              directory tree.
  13240.  
  13241.  
  13242.              13.8. Menu Commands, Displaying Files and External Programs
  13243.  
  13244.              The menu_cmd and display_file functions are used to run in-
  13245.              ternal Maximus menu commands and display .bbs files, respec-
  13246.              tively.
  13247.  
  13248.              The shell function spawns an external program, such as a
  13249.              .exe, .bat, or .cmd file.
  13250.  
  13251.  
  13252.              13.9. Download Queue
  13253.  
  13254.              The tag_queue_file function is used to add a file to the
  13255.              download queue. The other tag_queue_* functions also allow a
  13256.              MEX program to retrieve information about existing files in
  13257.              the queue.
  13258.  
  13259.              To send a file to the user, the program must first queue the
  13260.              file using tag_queue_file. Next, it must call menu_cmd and
  13261.              instruct it to run the internal MNU_FILE_DOWNLOAD menu op-
  13262.              tion. This will initiate the normal download sequence. Maxi-
  13263.              mus will prompt the user for a protocol if necessary, and it
  13264.              will also allow the user to select other files to download.
  13265.  
  13266.              If this behavior is not desired, the MEX program can:
  13267.  
  13268.  
  13269.  
  13270.              13. Interfacing MEX with Maximus                          240
  13271.  
  13272.              *  Set the usr.def_proto field to one of the PROTOCOL_* con-
  13273.                 stants in max.mh. This causes Maximus to skip the "Select
  13274.                 protocol:" prompt and forces the user to download using a
  13275.                 specific protocol.
  13276.  
  13277.              *  Insert a "|" into the input global variable. This adds a
  13278.                 carriage return to the stacked input string, so the
  13279.                 "File(s) to download (#2):" prompt will be skipped and the
  13280.                 file will be sent immediately.
  13281.  
  13282.  
  13283.              13.10. Other Functions
  13284.  
  13285.              While this section has touched on the major functions that
  13286.              are used to interface with Maximus, many of the other func-
  13287.              tions in the run-time library can be used to modify Maximus's
  13288.              internal behavior. Please consult the function list in sec-
  13289.              tion 15 for more information.
  13290.  
  13291.  
  13292.  
  13293.  
  13294.  
  13295.  
  13296.  
  13297.  
  13298.                                                  14. MEX Compiler Reference
  13299.  
  13300.  
  13301.              14.1. Command Line Format
  13302.  
  13303.              The format for invoking the MEX compiler is given below:
  13304.  
  13305.                 MEX filename [-a] [-hsize] [-s] [-q]
  13306.  
  13307.              filename is the name of the MEX source file to compile. If no
  13308.              file extension is specified, .mex is assumed.
  13309.  
  13310.              The command line switches supported by MEX are shown below in
  13311.              Table 14.1:
  13312.  
  13313.              Table 14.1 MEX Command Line Switches
  13314.  
  13315.              Parameter    Description
  13316.  
  13317.              -a           Display addresses instead of symbolic names
  13318.                           when writing quad output. This parameter is
  13319.                           only valid when used in conjunction with the -q
  13320.                           parameter.
  13321.              -h<size>     Set the program heap size to <size>. The heap
  13322.                           is used for storing dynamic strings. The de-
  13323.                           fault heap size is 8192 bytes, but this limit
  13324.                           may need to be increased if a large number of
  13325.                           strings are used within one MEX program.
  13326.              -s<size>     Set the program stack size to <size>. The stack
  13327.                           is used for storing local variables and for
  13328.                           performing recursive function calls. The de-
  13329.                           fault stack size is 2048 bytes, but this limit
  13330.                           may need to be increased if a program uses many
  13331.                           local variables or makes a large number of re-
  13332.                           cursive function calls.
  13333.              -q           Instead of writing out a .vm file as p-code,
  13334.                           write the output to the console as a sequence
  13335.                           of ASCII quadruples (quads). This is equivalent
  13336.                           to the "assembler output" option of most na-
  13337.                           tive-code compilers. A quad is a 4-tuple con-
  13338.                           sisting of an operator, two input arguments,
  13339.                           and a destination. The quad listing can some-
  13340.                           times be used to help debug a program.
  13341.  
  13342.  
  13343.  
  13344.              The MEX compiler converts the MEX program source into com-
  13345.              piled p-code which is interpreted at run-time by Maximus.
  13346.              Generating p-code has two main benefits over generating na-
  13347.              tive object code:
  13348.  
  13349.  
  13350.  
  13351.              14. MEX Compiler Reference                                242
  13352.  
  13353.              *  p-code is not operating system or processor-specific, so
  13354.                 the same MEX program can run under either 16-bit DOS or 32-
  13355.                 bit OS/2 environments without recompilation.
  13356.  
  13357.              *  Although executing p-code is somewhat slower than executing
  13358.                 native object code, over 120 functions are included in the
  13359.                 standard MEX run-time library that can be used to access
  13360.                 internal Maximus features, perform input and output, ma-
  13361.                 nipulate strings, and manage information. Since these li-
  13362.                 brary functions are embedded within Maximus, they run at
  13363.                 native object code speeds. The more a MEX program takes ad-
  13364.                 vantage of the run-time library, the faster it runs.
  13365.  
  13366.  
  13367.              14.2. Environment Variables
  13368.  
  13369.              When searching for files specified in #include directives,
  13370.              the MEX compiler will first look for the include file rela-
  13371.              tive to the current directory. If the file cannot be found
  13372.              there, MEX will examine the MEX_INCLUDE environment variable.
  13373.              This variable must contain a semicolon-delimited list of
  13374.              paths where MEX include files can be found. Maximus will then
  13375.              search all of the directories listed in this environment
  13376.              variable.
  13377.  
  13378.              For example, by entering this at the command prompt:
  13379.  
  13380.                 SET MEX_INCLUDE=d:\max\m;e:\mextest
  13381.  
  13382.              when MEX encounters an #include directive, if the file cannot
  13383.              be found in the current directory, it will look for the in-
  13384.              clude file in the d:\max\m and e:\mextest directories.
  13385.  
  13386.  
  13387.              14.3. Error Messages and Warnings
  13388.  
  13389.              The following error messages and warnings are generated by
  13390.              the MEX compiler:
  13391.  
  13392.  
  13393.              14.3.1. General Syntax Errors
  13394.  
  13395.              2000 syntax error near symbol
  13396.  
  13397.                   MEX could not make any sense of the source code that is
  13398.                   near the symbol token. Check your code for misplaced
  13399.                   semicolons or other common errors.
  13400.  
  13401.              2001 invalid identifier type
  13402.  
  13403.                   You attempted to use a function or structure name as a
  13404.                   variable.
  13405.  
  13406.  
  13407.  
  13408.              14. MEX Compiler Reference                                243
  13409.  
  13410.              14.3.2. Preprocessor Errors
  13411.  
  13412.              2100 can't open file symbol for read
  13413.  
  13414.                   MEX could not find the named file. Ensure that the file
  13415.                   exists and that your MEX_INCLUDE environment variable is
  13416.                   set correctly.
  13417.  
  13418.              2101 invalid #include directive
  13419.  
  13420.                   MEX could not make any sense of an include directive.
  13421.                   Ensure that a filename is specified.
  13422.  
  13423.              2102 invalid #include file
  13424.  
  13425.                   MEX could not make any sense of an include filename. En-
  13426.                   sure that the filename is surrounded by angle brackets.
  13427.  
  13428.              2103 too many nested include files
  13429.  
  13430.                   MEX can only handle up to 16 nested include files at a
  13431.                   time. Reduce the number of nested #include directives.
  13432.  
  13433.              2104 invalid #ifdef/#ifndef
  13434.  
  13435.                   The #ifdef or #ifndef statement is invalid. Ensure that
  13436.                   a proper constant or define follows the #ifdef or
  13437.                   #ifndef directive.
  13438.  
  13439.              2105 too many nested #ifdef/#ifndef
  13440.  
  13441.                   MEX only supports up to 8 nested #ifdef or #ifndef
  13442.                   statements.
  13443.  
  13444.              2106 unmatched #ifdef directive
  13445.  
  13446.                   A matching #endif could not be found for an #ifdef di-
  13447.                   rective.
  13448.  
  13449.              2107 unmatched #endif directive
  13450.  
  13451.                   A matching #ifdef could not be found for this #endif di-
  13452.                   rective.
  13453.  
  13454.              2108 unmatched #else directive
  13455.  
  13456.                   A matching #ifdef could not be found for this #else di-
  13457.                   rective.
  13458.  
  13459.              2109 unmatched #elifdef
  13460.  
  13461.                   A matching #ifdef could not be found for this #elifdef
  13462.                   directive.
  13463.  
  13464.  
  13465.  
  13466.              14. MEX Compiler Reference                                244
  13467.  
  13468.              2110 invalid #define
  13469.  
  13470.                   This #define directive has an incorrect format. Ensure
  13471.                   that it includes a variable to be defined.
  13472.  
  13473.              2111 macro symbol is already defined and is not identical
  13474.  
  13475.                   The symbol macro was defined using a previous #define
  13476.                   statement, but the current #define directive attempts to
  13477.                   change the value of symbol to something else.
  13478.  
  13479.              2112 #error directive: string
  13480.  
  13481.                   An #error directive was encountered in the program
  13482.                   source.
  13483.  
  13484.              2113 unknown directive symbol
  13485.  
  13486.                   An unknown preprocessor directive was encountered in the
  13487.                   source file.
  13488.  
  13489.  
  13490.              14.3.3. Lexical Errors
  13491.  
  13492.              2200 unterminated character constant
  13493.  
  13494.                   A character constant was specified, but it included a
  13495.                   newline or end-of-file instead of a character.
  13496.  
  13497.              2201 unterminated string constant
  13498.  
  13499.                   A string constant was specified, but it did not include
  13500.                   a closing double quote.
  13501.  
  13502.              2202 invalid character constant
  13503.  
  13504.                   A character constant was specified, but it did not in-
  13505.                   clude a closing single quote.
  13506.  
  13507.              2203 invalid hex escape sequence "\xsymbol"
  13508.  
  13509.                   The specified hexadecimal escape sequence is not a valid
  13510.                   hexadecimal number.
  13511.  
  13512.              2204 invalid character symbol
  13513.  
  13514.                   An invalid character was found in the source file, such
  13515.                   as an unrecognized punctuation symbol or a high-bit
  13516.                   character.
  13517.  
  13518.  
  13519.  
  13520.              14. MEX Compiler Reference                                245
  13521.  
  13522.              14.3.4. Type Mismatch Errors
  13523.  
  13524.              2300 type must not be `void'
  13525.  
  13526.                   The void type can only be used in certain locations,
  13527.                   such as in function return values and in "void ref"
  13528.                   function parameters.
  13529.  
  13530.              2301 symbol symbol is not a structure type
  13531.  
  13532.                   You attempted to use symbol as a structure tag, even
  13533.                   though no structure type definition for that tag was
  13534.                   found.
  13535.  
  13536.              2302 invalid type symbol for type statement
  13537.  
  13538.                   The argument for a if, while, for, or do .. while ex-
  13539.                   pression was not correct. Only char, int, and long can
  13540.                   be used in these expressions.
  13541.  
  13542.              2303 can't use function as a variable
  13543.  
  13544.                   You attempted to use a function name in a context that
  13545.                   required a variable name.
  13546.  
  13547.              2304 the type `void' cannot have a value
  13548.  
  13549.                   You attempted to manipulate a function returning void as
  13550.                   part of an expression.
  13551.  
  13552.              2305 invalid type conversion: type1 -> type2
  13553.  
  13554.                   It is impossible to convert an object of type1 to type2.
  13555.                   This is usually the result of incompatible types for ex-
  13556.                   plicit casts, passing parameters to functions, and pass-
  13557.                   ing back function return values.
  13558.  
  13559.              2306 symbol must be an array
  13560.  
  13561.                   You attempted to use the array operator ("[" and "]")
  13562.                   on the variable symbol which is not an array.
  13563.  
  13564.              2107 can't use [] on a non-array
  13565.  
  13566.                   An expression on the specified line cannot be used with
  13567.                   the array operator.
  13568.  
  13569.              2308 invalid index type for array symbol
  13570.  
  13571.                   The index type used to reference an array must be inte-
  13572.                   gral: either char, int, or long. The array symbol cannot
  13573.                   be indexed using any other types.
  13574.  
  13575.  
  13576.  
  13577.              14. MEX Compiler Reference                                246
  13578.  
  13579.              2309 out-of-range subscript (num) for array symbol
  13580.  
  13581.                   You attempted to access a subscript that was outside of
  13582.                   the bounds for the array symbol.
  13583.  
  13584.              2310 dot operator can only be used with structures
  13585.  
  13586.                   You attempted to use the dot operator (".") with a vari-
  13587.                   able that was not a structure.
  13588.  
  13589.              2311 symbol is not a member of struct name
  13590.  
  13591.                   The field symbol was not found in the structure defini-
  13592.                   tion for the structure with a tag name of name.
  13593.  
  13594.              2312 symbol not a goto label
  13595.  
  13596.                   The target of a goto must be a label, not a variable or
  13597.                   a function name.
  13598.  
  13599.              2313 lvalue required
  13600.  
  13601.                   The target of an assignment must be a simple variable or
  13602.                   the result of the array or structure operators. You can-
  13603.                   not assign a value to an expression. (For example, "i+2
  13604.                   := 2" is invalid, since "i+2" is an expression and can-
  13605.                   not be assigned a value.)
  13606.  
  13607.              2314 cannot apply unary minus to symbol
  13608.  
  13609.                   The unary minus operator cannot be applied to the symbol
  13610.                   object. The unary minus can only be applied to the char,
  13611.                   int, and long types.
  13612.  
  13613.              2315 declared array must have upper bound
  13614.  
  13615.                   An array declared in a function body must have an upper
  13616.                   bound. Only arrays declared as function parameters can
  13617.                   omit the upper bound.
  13618.  
  13619.              2316 cannot apply sizeof() to a boundless array
  13620.  
  13621.                   The sizeof operator can only be used on arrays of finite
  13622.                   dimensions.
  13623.  
  13624.  
  13625.              14.3.5. Symbol Table Errors
  13626.  
  13627.              2400 redeclaration of symbol
  13628.  
  13629.                   The variable or function symbol has already been defined
  13630.                   in this scope.
  13631.  
  13632.  
  13633.  
  13634.              14. MEX Compiler Reference                                247
  13635.  
  13636.              2401 redeclaration of structure symbol
  13637.  
  13638.                   The structure type symbol has already been declared in
  13639.                   this scope.
  13640.  
  13641.              2402 undefined structure name: symbol
  13642.  
  13643.                   The structure tag symbol is unknown.
  13644.  
  13645.              2403 symbol symbol is not a structure type
  13646.  
  13647.                   The tag symbol specified for a structure was the name of
  13648.                   another variable or function, rather than a proper
  13649.                   structure tag.
  13650.  
  13651.              2404 undefined label symbol
  13652.  
  13653.                   The label symbol was not found anywhere in the function
  13654.                   in which it was used.
  13655.  
  13656.              2405 undefined variable symbol
  13657.  
  13658.                   The variable symbol has not been declared.
  13659.  
  13660.              2406 struct symbol must be declared before use
  13661.  
  13662.                   Your program attempted to use a structure type that has
  13663.                   not yet been defined.
  13664.  
  13665.              2407 invalid redeclaration of function symbol
  13666.  
  13667.                   A function was declared using the same name as a global
  13668.                   variable or structure tag.
  13669.  
  13670.              2408 redeclaration of argument symbol
  13671.  
  13672.                   The function argument symbol has been declared twice in
  13673.                   the parameter list.
  13674.  
  13675.              2409 redeclaration of function body for symbol
  13676.  
  13677.                   The function body for symbol has already been encoun-
  13678.                   tered in the source file. A function can only be defined
  13679.                   once.
  13680.  
  13681.              2410 invalid range: `num .. num'
  13682.  
  13683.                   The lower bound for an array was greater than the upper
  13684.                   bound.
  13685.  
  13686.  
  13687.  
  13688.              14. MEX Compiler Reference                                248
  13689.  
  13690.              14.3.6. Function-Related Errors
  13691.  
  13692.              2501 argument mismatch: function=type, prototype=type
  13693.  
  13694.                   The type of parameter specified in the function's argu-
  13695.                   ment list differs from that specified in the function
  13696.                   prototype.
  13697.  
  13698.              2502 too many arguments in function declaration
  13699.  
  13700.                   Too many arguments were specified in the function decla-
  13701.                   ration. The function prototype specified a fewer number
  13702.                   of arguments.
  13703.  
  13704.              2503 too few arguments in function declaration
  13705.  
  13706.                   Too few arguments were specified in the function decla-
  13707.                   ration. The function prototype specifies a larger number
  13708.                   of arguments.
  13709.  
  13710.              2504 call to symbol with no prototype
  13711.  
  13712.                   A function was called, but the function was neither de-
  13713.                   fined nor prototype earlier in the source file.
  13714.  
  13715.              2505 variable symbol is not a function
  13716.  
  13717.                   You attempted to make a call to symbol, even though it
  13718.                   is a variable and not a function.
  13719.  
  13720.              2506 lvalue required (arg num of symbol)
  13721.  
  13722.                   In a call to function symbol, argument number num is
  13723.                   pass-by-reference. This means that a variable of the ap-
  13724.                   propriate type (and not an expression or constant) must
  13725.                   be passed for the specified argument.
  13726.  
  13727.              2507 not enough arguments in call to symbol
  13728.  
  13729.                   Not enough arguments were specified in the call to sym-
  13730.                   bol, relative to the function prototype.
  13731.  
  13732.              2508 too many arguments in call to symbol
  13733.  
  13734.                   Too many arguments were specified in the call to symbol,
  13735.                   relative to the function prototype.
  13736.  
  13737.              2509 void function cannot return a value
  13738.  
  13739.                   You attempted to return a value from a function that was
  13740.                   declared as returning void.
  13741.  
  13742.  
  13743.  
  13744.              14. MEX Compiler Reference                                249
  13745.  
  13746.              2510 non-void function must return a value
  13747.  
  13748.                   You used a simple "return;" statement with no value,
  13749.                   even though the function itself must return a value.
  13750.  
  13751.  
  13752.              14.3.7. Warnings
  13753.  
  13754.              3000 constant truncated: symbol
  13755.  
  13756.                   The numeric constant symbol was too long and had to be
  13757.                   truncated.
  13758.  
  13759.              3001 identifier truncated: symbol
  13760.  
  13761.                   The identifier symbol was too long and had to be trun-
  13762.                   cated at 32 characters.
  13763.  
  13764.              3002 meaningless use of an expression
  13765.  
  13766.                   You attempted to use the equality operator in a way that
  13767.                   does not make sense. For example, the following line of
  13768.                   code:
  13769.  
  13770.                      i = 2;
  13771.  
  13772.                   will produce this warning because you are simply compar-
  13773.                   ing the value of i to 2, but then throwing away the re-
  13774.                   sult of the comparison. You probably meant to write:
  13775.  
  13776.                      i := 2;
  13777.  
  13778.                   which assigns the value 2 to i.
  13779.  
  13780.  
  13781.  
  13782.  
  13783.  
  13784.  
  13785.  
  13786.  
  13787.                                                   15. MEX Library Reference
  13788.  
  13789.              This section describes all of the functions and structures
  13790.              available in the standard MEX run-time library.
  13791.  
  13792.  
  13793.              15.1. Global Variables and Data Structures
  13794.  
  13795.              Maximus exports certain global variables to all MEX programs.
  13796.              These variables can be used to track the internal system
  13797.              state, including information about the current message and
  13798.              file area, screen settings, user information, and more.
  13799.  
  13800.              All of the following global variables are declared in the
  13801.              max.mh include file. The following line must be present at
  13802.              the top of a MEX source file to access these variables:
  13803.  
  13804.                 #include <max.mh>
  13805.  
  13806.  
  13807.              15.1.1. Strings Exported by Maximus
  13808.  
  13809.              This section describes the strings that are exported by Maxi-
  13810.              mus to all MEX programs.
  13811.  
  13812.  
  13813.  
  13814.              input
  13815.  
  13816.  
  13817.  
  13818.  
  13819.  Declaration string: input;
  13820.  
  13821.  Description This string contains the current "stacked keyboard input
  13822.              string" used by Maximus. The input string contains a sequence
  13823.              of keys that will be used to try to satisfy the input re-
  13824.              quirements of following calls to the input_ch, input_str, and
  13825.              input_list functions. The internal Maximus input commands
  13826.              also use this buffer for their own input.
  13827.  
  13828.              The internal Maximus input functions also try to take their
  13829.              input from this string before prompting the user for input.
  13830.  
  13831.              The input_* functions will draw as many characters as neces-
  13832.              sary from this string to satisfy an input request. (In the
  13833.              case of input_ch or input_list, only a single character will
  13834.              normally be removed. In the case of input_str, a single word
  13835.              or an entire line is normally removed.)
  13836.  
  13837.  
  13838.  
  13839.              15. MEX Library Reference                                 252
  13840.  
  13841.              This string can be modified by MEX programs.
  13842.  
  13843.  
  13844.              15.1.2. Structures Exported by Maximus
  13845.  
  13846.              This section describes the structures that are exported by
  13847.              Maximus to all MEX programs:
  13848.  
  13849.  
  13850.  
  13851.              struct _instancedata
  13852.  
  13853.  
  13854.  
  13855.  
  13856.  Declaration struct _instancedata: id;
  13857.  
  13858.  Description This structure contains information about the current Maximus
  13859.              session. The contents of the structure are shown below in
  13860.              Table 15.1:
  13861.  
  13862.              Table 15.1 struct _instancedata
  13863.  
  13864.               Field          Type      Description
  13865.  
  13866.               instant_video  int       This controls the "instant video"
  13867.                                        setting. If instant video is en-
  13868.                                        abled, output displayed by print
  13869.                                        will be shown on the local screen
  13870.                                        as soon as the print function is
  13871.                                        called.
  13872.                                        However, screen updating can be a
  13873.                                        slow process, so it is sometimes
  13874.                                        more efficient to disable local
  13875.                                        screen writes, perform many print
  13876.                                        calls, and to then display the lo-
  13877.                                        cal screen again (using the vid-
  13878.                                        sync function) after all of the
  13879.                                        print calls have been completed.
  13880.                                        To disable the instant screen up-
  13881.                                        dating feature, set
  13882.                                        id.instant_video to 0. While this
  13883.                                        variable is set to 0, the print
  13884.                                        function will not cause the local
  13885.                                        screen to be updated.
  13886.                                        However, be warned that some in-
  13887.                                        ternal Maximus functions will up-
  13888.                                        date the screen regardless of this
  13889.                                        setting. Examples of this are in-
  13890.                                        put_ch, input_str and input_list.
  13891.                                        This field can be modified by MEX
  13892.                                        programs.
  13893.               task_num       unsigned  The current task number.
  13894.  
  13895.  
  13896.  
  13897.              15. MEX Library Reference                                 253
  13898.  
  13899.                              int
  13900.               local          int       TRUE if the caller is logged on at
  13901.                                        the local console.
  13902.                port          int       Under DOS: the current COM port
  13903.                                        number.
  13904.                                        Under OS/2: the current communica-
  13905.                                        tions handle.
  13906.               speed          unsigned  The user's connection speed, in
  13907.                              long      bits per second (bps).
  13908.               alias_system   int       TRUE if the system supports ali-
  13909.                                        ases ("Alias System" in the system
  13910.                                        control file).
  13911.               ask_name       int       TRUE if the system will ask the
  13912.                                        user for a real name.
  13913.               use_umsgid     int       TRUE if the system displays UMS-
  13914.                                        GIDs instead of message numbers.
  13915.  
  13916.  
  13917.  
  13918.              struct _marea
  13919.  
  13920.  
  13921.  
  13922.  
  13923.  Declaration struct _marea: marea;
  13924.  
  13925.  Description This structure contains information about the current message
  13926.              area. Structures of this type are also returned by the msga-
  13927.              reafind* functions. The contents of the structure are shown
  13928.              below in Table 15.2:
  13929.  
  13930.              Table 15.2 struct _marea
  13931.  
  13932.               Field         Type      Description
  13933.  
  13934.               name          string    This name of the message area.
  13935.               descript      string    The description for the message
  13936.                                       area.
  13937.               path          string    The path and/or filename of the
  13938.                                       message area. (*.MSG areas will be
  13939.                                       provided as a path; Squish areas
  13940.                                       will be provided as a path and
  13941.                                       filename.)
  13942.               tag           string    The tag for this area (for use in
  13943.                                       EchoMail applications).
  13944.               attachpath    string    The path for local file attaches.
  13945.               barricade     string    The barricade filename for this
  13946.                                       area.
  13947.               division      int       Non-zero if this is a message di-
  13948.                                       vision starting or ending record.
  13949.                                       (1=beginning; 2=ending.)
  13950.               type          int       Message area type. One of either
  13951.                                       MSGTYPE_SQUISH or MSGTYPE_SDM
  13952.  
  13953.  
  13954.  
  13955.              15. MEX Library Reference                                 254
  13956.  
  13957.                                       (*.MSG).
  13958.               attribs       int       Message area attributes. See the
  13959.                                       MA_* definitions in max.mh.
  13960.  
  13961.  
  13962.  
  13963.              struct _farea
  13964.  
  13965.  
  13966.  
  13967.  
  13968.  Declaration struct _farea: farea;
  13969.  
  13970.  Description This structure contains information about the current file
  13971.              area. Structures of this type are also returned by the
  13972.              fileareafind* functions. The contents of this structure are
  13973.              shown in Table 15.3:
  13974.  
  13975.              Table 15.3 struct _farea
  13976.  
  13977.               Field      Type     Description
  13978.  
  13979.               name       string   This name of the file area.
  13980.               descript   string   The description for the file area.
  13981.               downpath   string   The download path for this file
  13982.                                   area.
  13983.               uppath     string   The upload path for this file area.
  13984.               filesbbs   string   Path to the files.bbs-like list for
  13985.                                   this file area.
  13986.               barricade  string   The barricade filename for this
  13987.                                   area.
  13988.               division   int      Non-zero if this is a file division
  13989.                                   starting or ending record.
  13990.                                   (1=beginning; 2=ending.)
  13991.               attribs    int      File area attributes. See the FA_*
  13992.                                   definitions in max.mh.
  13993.  
  13994.  
  13995.  
  13996.              struct _msg
  13997.  
  13998.  
  13999.  
  14000.  
  14001.  Declaration struct _msg: msg;
  14002.  
  14003.  Description This structure contains the current message number and other
  14004.              related information. The contents of the structure are shown
  14005.              below in Table 15.4:
  14006.  
  14007.  
  14008.  
  14009.              15. MEX Library Reference                                 255
  14010.  
  14011.              Table 15.4 struct _msg
  14012.  
  14013.               Field       Type     Description
  14014.  
  14015.               current     long     The current message number, or if Use
  14016.                                    UMSGIDs is enabled, the UMSGID of the
  14017.                                    current message number. This field
  14018.                                    can be modified by MEX programs.
  14019.               high        long     The highest message number in the
  14020.                                    current area, or if Use UMSGIDs is
  14021.                                    enabled, the UMSGID of the highest
  14022.                                    message number.
  14023.               num         long     The number of messages in the current
  14024.                                    area.
  14025.               direction   int      Message reading direction. 1 = next;
  14026.                                    0 = prior.
  14027.  
  14028.  
  14029.  
  14030.              struct _usr
  14031.  
  14032.  
  14033.  
  14034.  
  14035.  Declaration struct _usr: usr;
  14036.  
  14037.  Description This structure contains information about the current user.
  14038.              Structures of this type are also manipulated by the user*
  14039.              functions.
  14040.  
  14041.              Table 15.5 describes the contents of this structure. All
  14042.              fields in this structure can be modified by MEX programs.
  14043.  
  14044.              Table 15.5 struct _usr
  14045.  
  14046.               Field            Type       Description
  14047.  
  14048.               name             string     The user's name.
  14049.               city             string     The user's city and
  14050.                                           state/province.
  14051.               alias            string     The user's alias.
  14052.               phone            string     The user's voice telephone
  14053.                                           number
  14054.               lastread_ptr     unsigned   An integer that is unique
  14055.                                int        among all users in the sys-
  14056.                                           tem. This number is used as
  14057.                                           an index for the lastread
  14058.                                           pointers in the Squish SQI
  14059.                                           files, to find records in the
  14060.                                           \max\olr\dats directory, and
  14061.                                           in numerous other places.
  14062.               pwd              string     The user's password. If the
  14063.                                           "usr.encrypted" flag is set,
  14064.  
  14065.  
  14066.  
  14067.              15. MEX Library Reference                                 256
  14068.  
  14069.                                           this may not be a readable
  14070.                                           password.
  14071.               times            unsigned   The number of previous calls
  14072.                                int        to the system made by this
  14073.                                           user.
  14074.               help             char       The user's help level.
  14075.                                           (Novice = 6; Regular = 4; Ex-
  14076.                                           pert = 2.)
  14077.               video            char       The user's video mode. (0 =
  14078.                                           TTY; 1 = ANSI; 2 = AVATAR.)
  14079.               nulls            char       The number of NUL characters
  14080.                                           sent after a carriage return.
  14081.               hotkeys          char       TRUE if hotkeys are enabled.
  14082.               notavail         char       TRUE if the user is not
  14083.                                           available for multinode chat-
  14084.                                           ting.
  14085.               fsr              char       TRUE if the user has enabled
  14086.                                           the full-screen reader.
  14087.               nerd             char       TRUE if the user is a nerd
  14088.                                           (meaning that the user's
  14089.                                           yells are silenced).
  14090.               noulist          char       TRUE if the user does not
  14091.                                           show up in the userlist.
  14092.               tabs             char       TRUE if the user's terminal
  14093.                                           can handle tab characters.
  14094.               encrypted        char       TRUE if the user's password
  14095.                                           is encrypted.
  14096.               rip              char       TRUE if the user has enabled
  14097.                                           RIPscrip graphics.
  14098.               badlogon         char       TRUE if the user's last log-
  14099.                                           on attempt resulted in a
  14100.                                           failed password.
  14101.               ibmchars         char       TRUE if the user has enabled
  14102.                                           the high-bit IBM character
  14103.                                           set.
  14104.               bored            char       TRUE if the line editor is
  14105.                                           enabled; otherwise, the full-
  14106.                                           screen MaxEd is used.
  14107.               more             char       TRUE if the "More" prompt is
  14108.                                           enabled.
  14109.               configured       char       TRUE if the user's city and
  14110.                                           password fields have been
  14111.                                           set.
  14112.               cls              char       TRUE if the user's terminal
  14113.                                           can handle screen clears.
  14114.               priv             unsigned   The user's privilege level.
  14115.                                int
  14116.               dataphone        string     The user's data phone number.
  14117.               time             unsigned   The length of time (in min-
  14118.                                int        utes) that the user has been
  14119.                                           on-line today.
  14120.               deleted          char       TRUE if the user has been de-
  14121.                                           leted.
  14122.  
  14123.  
  14124.  
  14125.              15. MEX Library Reference                                 257
  14126.  
  14127.               permanent        char       TRUE if the user is undelet-
  14128.                                           able.
  14129.               msgs_posted      long       The total number of messages
  14130.                                           posted by this user.
  14131.               msgs_read        long       The total number of messages
  14132.                                           read by this user.
  14133.               width            char       The width of the caller's
  14134.                                           screen. Also see the
  14135.                                           term_width and screen_width
  14136.                                           functions in the run-time li-
  14137.                                           brary reference.
  14138.               len              char       The height of the caller's
  14139.                                           screen. Also see the
  14140.                                           term_length and screen_length
  14141.                                           functions in the run-time li-
  14142.                                           brary reference.
  14143.               credit           unsigned   User's NetMail credit, in
  14144.                                int        cents.
  14145.               debit            unsigned   User's NetMail debit, in
  14146.                                int        cents.
  14147.               xp_priv          unsigned   Priv level to which the user
  14148.                                int        will be demoted when the cur-
  14149.                                           rent subscription expires.
  14150.               xp_date          struct     Date and time for the user's
  14151.                                _stamp     subscription expiry.
  14152.               xp_mins          unsigned   Number of minutes remaining
  14153.                                long       in the user's subscription.
  14154.               expdate          char       TRUE if the user expires
  14155.                                           based on the xp_date field.
  14156.               expmins          char       TRUE if the user expires
  14157.                                           based on the xp_mins field.
  14158.               expdemote        char       TRUE if the user is to be de-
  14159.                                           moted to the value in the
  14160.                                           xp_priv field when the sub-
  14161.                                           scription expires.
  14162.               expaxe           char       TRUE if Maximus should hang
  14163.                                           up on the caller when the
  14164.                                           subscription expires.
  14165.               sex              char       The user's gender: either
  14166.                                           SEX_MALE, SEX_FEMALE or
  14167.                                           SEX_UNKNOWN.
  14168.               ludate           struct     Date of the user's last call.
  14169.                                _stamp
  14170.               xkeys            string     The user's keys (as a
  14171.                                           string).
  14172.               lang             char       The user's current language
  14173.                                           number. The lan-
  14174.                                           guage_num_to_string function
  14175.                                           is to translate this number
  14176.                                           into a string.
  14177.               def_proto        char       The user's default protocol.
  14178.                                           This can be one of the PROTO-
  14179.                                           COL_* defines from max.mh, or
  14180.  
  14181.  
  14182.  
  14183.              15. MEX Library Reference                                 258
  14184.  
  14185.                                           it can be a positive index to
  14186.                                           indicate an external proto-
  14187.                                           col. The proto-
  14188.                                           col_num_to_string function is
  14189.                                           used to translate all of
  14190.                                           these numbers (for both in-
  14191.                                           ternal and external proto-
  14192.                                           cols) into strings.
  14193.               up               unsigned   Total kilobytes uploaded for
  14194.                                long       all calls.
  14195.               down             unsigned   Total kilobytes downloaded
  14196.                                long       for all calls.
  14197.               downtoday        unsigned   Total kilobytes downloaded
  14198.                                long       today.
  14199.               msg              string     The user's current message
  14200.                                           area.
  14201.               files            string     The user's current file area.
  14202.               compress         char       The user's default compres-
  14203.                                           sion program. The compres-
  14204.                                           sor_num_to_string function is
  14205.                                           used to translate this number
  14206.                                           into a string.
  14207.               dob              string     The caller's date of birth
  14208.                                           (in "yyyy.mm.dd" format).
  14209.               date_1stcall     struct     Date/time of the user's first
  14210.                                _stamp     call to the system.
  14211.               date_pwd_chg     struct     Date/time of the user's most
  14212.                                _stamp     recent password change.
  14213.               nup              unsigned   Total number of files up-
  14214.                                long       loaded to the system.
  14215.               ndown            unsigned   Total number of files down-
  14216.                                long       loaded from the system.
  14217.               ndowntoday       unsigned   Number of files downloaded
  14218.                                long       from the system today.
  14219.               time_added       unsigned   Credits added to the user's
  14220.                                int        time today (for chatting with
  14221.                                           the SysOp or for upload time
  14222.                                           credits).
  14223.               point_credit     unsigned   Total number of point cred-
  14224.                                long       its.
  14225.               point_debit      unsigned   Total number of point debits.
  14226.                                long
  14227.               date_newfile     struct     Date/time of last "new files"
  14228.                                _stamp     search.
  14229.               call             unsigned   Number of previous calls to-
  14230.                                int        day.
  14231.  
  14232.  
  14233.  
  14234.              15. MEX Library Reference                                 259
  14235.  
  14236.  
  14237.              struct _sys
  14238.  
  14239.  
  14240.  
  14241.  
  14242.  Declaration struct _sys: sys;
  14243.  
  14244.  Description This structure contains information about the current system
  14245.              screen display. The contents of this structure are described
  14246.              in Table 15.6:
  14247.  
  14248.              Table 15.6 struct _sys
  14249.  
  14250.               Field        Type  Description
  14251.  
  14252.               current_row  int   The current cursor row position.
  14253.               current_col  int   The current cursor column position.
  14254.               more_lines   int   The number of lines displayed since the
  14255.                                  last "More [Y,n,=]" prompt.
  14256.  
  14257.  
  14258.              15.1.3. Other Data Structures
  14259.  
  14260.              The structures listed in this section are not exported di-
  14261.              rectly by Maximus. However, the structures are used (directly
  14262.              or indirectly) by some of the functions in the run-time li-
  14263.              brary. Please consult section 15.3 for more information on
  14264.              the structures used by a particular function.
  14265.  
  14266.  
  14267.  
  14268.              struct _date
  14269.  
  14270.  
  14271.  
  14272.  
  14273.  Description This structure is used in various places to represent a sys-
  14274.              tem date. The contents of the structure are described in
  14275.              Table 15.7:
  14276.  
  14277.              Table 15.7 struct _date
  14278.  
  14279.               Field   Type   Description
  14280.  
  14281.               day     char   The day of the month. (1 = the first day.)
  14282.               month   char   The  month of the year. (1 = January.)
  14283.               year    char   The current year less 1980. (0 = 1980.)
  14284.  
  14285.  
  14286.  
  14287.              15. MEX Library Reference                                 260
  14288.  
  14289.  
  14290.              struct _time
  14291.  
  14292.  
  14293.  
  14294.  
  14295.  Description This function is used in various places to represent a system
  14296.              time. The contents of this structure are described in Table
  14297.              15.8:
  14298.  
  14299.              Table 15.8 struct _time
  14300.  
  14301.               Field  Type   Description
  14302.  
  14303.               hh     char   Hour in 24-hour format. (0 = midnight; 12 =
  14304.                             noon, 17 = 5 P.M.)
  14305.               mm     char   Minute. (Must be within 0 - 59 inclusive.)
  14306.               ss     char   Second. (Must be within 0 - 59 inclusive.)
  14307.  
  14308.  
  14309.  
  14310.  
  14311.  
  14312.              struct _stamp
  14313.  
  14314.  
  14315.  
  14316.  
  14317.  Description This structure contains copies of both a date and time struc-
  14318.              ture to provide a complete system timestamp. The contents of
  14319.              this structure are described in Table 15.9:
  14320.  
  14321.              Table 15.9 struct _stamp
  14322.  
  14323.               Field  Type              Description
  14324.  
  14325.               date   struct _date      A copy of the date structure.
  14326.               time   struct _time      A copy of the time structure.
  14327.  
  14328.  
  14329.  
  14330.  
  14331.  
  14332.              struct _cstat
  14333.  
  14334.  
  14335.  
  14336.  
  14337.  Description This structure is used by the chat_querystatus function. The
  14338.              contents of this structure are described in Table 15.10:
  14339.  
  14340.  
  14341.  
  14342.              15. MEX Library Reference                                 261
  14343.  
  14344.              Table 15.10 struct _cstat
  14345.  
  14346.               Field       Type     Description
  14347.  
  14348.               task_num    int      The user's task number
  14349.               avail       int      TRUE if the user is available for chat
  14350.               username    string   The user's name
  14351.               status      string   A status message describing the user's
  14352.                                    current actions.
  14353.  
  14354.  
  14355.  
  14356.              struct _ffind
  14357.  
  14358.  
  14359.  
  14360.  
  14361.  Description This structure is used by the filefind* functions to retrieve
  14362.              file status information. The contents of this structure are
  14363.              described in Table 15.11:
  14364.  
  14365.              Table 15.11 struct _ffind
  14366.  
  14367.               Field     Type             Description
  14368.  
  14369.               finddata  long             Instance-specific find data. This
  14370.                                          information is internal to Maxi-
  14371.                                          mus and must not be modified by
  14372.                                          the MEX program.
  14373.               filename  string           The name of the file.
  14374.               filesize  unsigned long    The size of the file.
  14375.               filedate  struct _stamp    The file's modification
  14376.                                          date/time.
  14377.               fileattr  unsigned int     The file's attributes. See the
  14378.                                          FA_* definitions in max.mh.
  14379.  
  14380.  
  14381.  
  14382.              struct _callinfo
  14383.  
  14384.  
  14385.  
  14386.  
  14387.  Description This function is used by the call* functions to read records
  14388.              from the caller log file. The contents of this structure are
  14389.              described in Table 15.12:
  14390.  
  14391.              Table 15.12 struct _callinfo
  14392.  
  14393.               Field         Type       Description
  14394.  
  14395.               name          string     The user's name.
  14396.               city          string     The user's city.
  14397.  
  14398.  
  14399.  
  14400.              15. MEX Library Reference                                 262
  14401.  
  14402.               login         struct     The user's log-on time.
  14403.                             _stamp
  14404.               logoff        struct     The user's log-off time.
  14405.                             _stamp
  14406.               task          int        The Maximus task number that cre-
  14407.                                        ated this record.
  14408.               flags         int        A combination of the CALL_* defi-
  14409.                                        nitions from max.mh.
  14410.               logon_priv    unsigned   The user's privilege level at
  14411.                             int        log-on.
  14412.               logon_xkeys   string     The user's key settings at log-
  14413.                                        on.
  14414.               logoff_priv   unsigned   The user's privilege level at
  14415.                             int        log-off.
  14416.               logoff_xkeys  string     The user's key settings at log-
  14417.                                        off.
  14418.               filesup       unsigned   Number of files uploaded in this
  14419.                             int        session.
  14420.               filedn        unsigned   Number of files downloaded in
  14421.                             int        this session.
  14422.               kbup          unsigned   Number of kilobytes uploaded in
  14423.                             int        this session.
  14424.               kbdn          unsigned   Number of kilobytes downloaded in
  14425.                             int        this session.
  14426.               calls         unsigned   Number of calls user made to the
  14427.                             int        system (as of when the record was
  14428.                                        written).
  14429.               read          unsigned   Number of messages read during
  14430.                             int        the session.
  14431.               posted        unsigned   Number of messages posted during
  14432.                             int        the session.
  14433.               paged         unsigned   Number of times that the SysOp
  14434.                             int        was paged during the session.
  14435.               added         int        Number of minutes that were cred-
  14436.                                        ited to the user's time for the
  14437.                                        day due to file uploads or chat-
  14438.                                        ting with the SysOp.
  14439.  
  14440.  
  14441.              15.2. Functions by Category
  14442.  
  14443.              This section gives a categorized listing of functions in the
  14444.              MEX run-time library. The functions are first listed by cate-
  14445.              gory; however, the next section gives a detailed description
  14446.              of each function, including the function prototype, argu-
  14447.              ments, return value, and overall function behavior.
  14448.  
  14449.  
  14450.              15.2.1. Screen Output and Display Formatting
  14451.  
  14452.              The functions listed in Table 15.13 are used for printing
  14453.              text, displaying output, and getting/setting screen format-
  14454.              ting information.
  14455.  
  14456.  
  14457.  
  14458.              15. MEX Library Reference                                 263
  14459.  
  14460.              Table 15.13 Screen Output and Display Formatting Functions
  14461.  
  14462.               Function       Description
  14463.  
  14464.               do_more        Optionally displays a "More [Y,n]" prompt.
  14465.               issnoop        Determines if "Snoop Mode" is active.
  14466.               print          Sends text to the user.
  14467.               reset_more     Resets the counter for a "More" prompt.
  14468.               screen_length  Returns the length of the system console.
  14469.               screen_width   Returns the width of the system console.
  14470.               set_output     Enables or disables local/remote output.
  14471.               set_textsize   Sets the size of the text window (for
  14472.                              RIPscrip graphics).
  14473.               snoop          Enables or disables "Snoop Mode."
  14474.               term_length    Returns the length of the user's virtual
  14475.                              terminal.
  14476.               term_width     Returns the width of the user's virtual
  14477.                              terminal.
  14478.               vidsync        Updates the local video screen after a
  14479.                              call to print.
  14480.  
  14481.  
  14482.              15.2.2. Keyboard Input
  14483.  
  14484.              The functions listed in Table 15.14 are used for getting in-
  14485.              put from the user and for processing keystrokes.
  14486.  
  14487.              Table 15.14 Keyboard Input Functions
  14488.  
  14489.               Function      Description
  14490.  
  14491.               getch         Returns the next raw keystroke entered by
  14492.                             the user.
  14493.               input_ch      Gets a character from the user (with format-
  14494.                             ting).
  14495.               input_list    Gets a character from the user (from a list
  14496.                             of choices).
  14497.               input_str     Gets an entire word or string from the user.
  14498.               iskeyboard    Determines if local keyboard mode is en-
  14499.                             abled.
  14500.               kbhit         Checks to see if the user has pressed a key.
  14501.               keyboard      Enables/disables local keyboard mode.
  14502.               localkey      Determines if the last keystroke was entered
  14503.                             by a remote user.
  14504.  
  14505.  
  14506.              15.2.3. External Programs, .BBS files, and Menu Options
  14507.  
  14508.              The functions listed in Table 15.15 are used to interface to
  14509.              non-MEX scripts or programs, such as .bbs files, Maximus menu
  14510.              commands, and external programs.
  14511.  
  14512.  
  14513.  
  14514.              15. MEX Library Reference                                 264
  14515.  
  14516.              Table 15.15 External Program Functions
  14517.  
  14518.               Function       Description
  14519.  
  14520.               display_file   Displays a .BBS, .GBS or .RBS file.
  14521.               menu_cmd       Runs most internal Maximus menu commands.
  14522.               shell          Shells to an external program (.exe, .bat,
  14523.                              .cmd, etc.)
  14524.  
  14525.  
  14526.  
  14527.              15.2.4. File I/O and Disk Operations
  14528.  
  14529.              The functions listed in Table 15.16 support opening, reading,
  14530.              writing, and performing other types of file manipulation and
  14531.              information-gathering.
  14532.  
  14533.              Table 15.16 File and Disk Operations
  14534.  
  14535.               Function    Description
  14536.  
  14537.               close       Closes a file handle.
  14538.               filecopy    Copies a file from one location to another.
  14539.               filedate    Retrieves the date for a file.
  14540.               fileexists  Determines if a file exists.
  14541.               filesize    Returns the size of a file.
  14542.               open        Opens a file for read or write.
  14543.               read        Reads a block from a file.
  14544.               readln      Reads an entire line from a file.
  14545.               remove      Deletes a file.
  14546.               rename      Renames a file.
  14547.               seek        Sets a file's "next read/write location"
  14548.                           pointer.
  14549.               tell        Returns a file's "next read/write location"
  14550.                           pointer.
  14551.               write       Write a block to a file.
  14552.               writeln     Write an entire line to a file.
  14553.  
  14554.  
  14555.  
  14556.              15.2.5. File Searching Operations
  14557.  
  14558.              The functions listed in Table 15.17 are used to expand file-
  14559.              name wildcards and/or perform file directory searches.
  14560.  
  14561.              Table 15.17 File Searching Operations
  14562.  
  14563.               Format          Description
  14564.  
  14565.               filefindclose   Terminates a file-find search.
  14566.               filefindfirst   Starts looking for a named file (or a
  14567.                               wildcard).
  14568.  
  14569.  
  14570.  
  14571.              15. MEX Library Reference                                 265
  14572.  
  14573.               filefindnext    Find the next file after starting a
  14574.                               search.
  14575.  
  14576.  
  14577.  
  14578.              15.2.6. Strings
  14579.  
  14580.              The functions listed in Table 15.18 are used for common
  14581.              string manipulation operations, such as padding, stripping,
  14582.              finding substrings, and more.
  14583.  
  14584.              Table 15.18 String Operations
  14585.  
  14586.               Function     Description
  14587.  
  14588.               strfind      Finds the index of a substring within another
  14589.                            string.
  14590.               stridx       Finds the index of a character within a
  14591.                            string.
  14592.               strlen       Returns the length of a string.
  14593.               strlower     Converts a string to lowercase.
  14594.               strpad       Right-pads a string with a certain character.
  14595.               strpadleft   Left-pads a string with a certain character.
  14596.               strridx      Returns the index of the rightmost character
  14597.                            within a string that contains a specific
  14598.                            value.
  14599.               strtok       Tokenizes a string.
  14600.               strupper     Converts a string to uppercase.
  14601.               strtrim      Remove unwanted characters on either end of a
  14602.                            string.
  14603.               substr       Extracts a substring from another, given the
  14604.                            substring's size and location.
  14605.  
  14606.  
  14607.  
  14608.              15.2.7. Time and Date
  14609.  
  14610.              The functions listed in Table 15.19 are used to check the
  14611.              current system time, in addition to setting and querying in-
  14612.              formation about the user's current time limit.
  14613.  
  14614.              Table 15.19 Time and Date Functions
  14615.  
  14616.               Function         Description
  14617.  
  14618.               long_to_stamp    Converts a long-format timestamp into a
  14619.                                string.
  14620.               stamp_string     Converts a stamp structure into a string.
  14621.               stamp_to_long    Converts a stamp structure into a long.
  14622.               time             Returns the current time as a long.
  14623.               time_check       Check the user's current time limit.
  14624.               timeadjust       Adjust a user's time limit.
  14625.               timeadjustsoft   Adjust a user's time limit without over-
  14626.  
  14627.  
  14628.  
  14629.              15. MEX Library Reference                                 266
  14630.  
  14631.                                running events.
  14632.               timeleft         Returns the length of time remaining in
  14633.                                this session.
  14634.               timeon           Returns the amount of time that the user
  14635.                                has been on-line.
  14636.               timestamp        Returns the current time as a stamp
  14637.                                structure.
  14638.               xfertime         Calculates the approximate time required
  14639.                                for a file transfer.
  14640.  
  14641.  
  14642.              15.2.8. Time Delay
  14643.  
  14644.              The function listed in Table 15.20 is used for pausing pro-
  14645.              gram operation.
  14646.  
  14647.              Table 15.20 Time Delay Functions
  14648.  
  14649.               Function   Description
  14650.  
  14651.               sleep      Causes the system to delay for a certain period
  14652.                          of time.
  14653.  
  14654.  
  14655.              15.2.9. Type Conversions
  14656.  
  14657.              The functions listed in Table 15.21 are used to convert data
  14658.              between the string type and one of the integral types.
  14659.  
  14660.              Table 15.21 Type Conversion Functions
  14661.  
  14662.               Function      Description
  14663.  
  14664.               itostr        Converts an integer to a string.
  14665.               ltostr        Converts a long to a string.
  14666.               strtoi        Converts a string to an integer.
  14667.               strtol        Converts a string to a long.
  14668.               uitostr       Converts an unsigned integer to a string.
  14669.               ultostr       Converts an unsigned long to a string.
  14670.  
  14671.  
  14672.              15.2.10. Modem and Communications
  14673.  
  14674.              The functions listed in Table 15.22 are used to directly con-
  14675.              trol the modem.
  14676.  
  14677.              Table 15.22 Modem and Communications Functions
  14678.  
  14679.               Function      Description
  14680.  
  14681.               carrier       Checks whether or not DCD is present.
  14682.               dcd_check     Enables or disables automatic DCD checking.
  14683.               mdm_command   Sends a command to the modem.
  14684.  
  14685.  
  14686.  
  14687.              15. MEX Library Reference                                 267
  14688.  
  14689.               mdm_flow      Enables or disables flow control.
  14690.  
  14691.  
  14692.              15.2.11. Message Areas
  14693.  
  14694.              The functions listed in Table 15.23 are used to select the
  14695.              current message area and to search the message area data
  14696.              file.
  14697.  
  14698.              Table 15.23 Message Area Functions
  14699.  
  14700.               Function           Description
  14701.  
  14702.               msg_area           Displays the message-area menu.
  14703.               msgareafindclose   Terminates a message-area finding ses-
  14704.                                  sion.
  14705.               msgareafindfirst   Starts a message-area finding session.
  14706.               msgareafindnext    Finds the next area in a message-area
  14707.                                  finding session.
  14708.               msgareafindprev    Finds the previous area in a message-
  14709.                                  area finding session.
  14710.               msgareaselect      Sets the user's current message area.
  14711.  
  14712.  
  14713.              15.2.12. File Areas
  14714.  
  14715.              The functions listed in Table 15.24 are used to select the
  14716.              current file area and to search the file area data file.
  14717.  
  14718.              Table 15.24 File Area Functions
  14719.  
  14720.               Function            Description
  14721.  
  14722.               file_area           Displays the file-area menu.
  14723.               fileareafindclose   Terminates a file-area finding ses-
  14724.                                   sion.
  14725.               fileareafindfirst   Starts a file-area finding session.
  14726.               fileareafindnext    Finds the next area in a file-area
  14727.                                   finding session.
  14728.               fileareafindprev    Finds the previous area in a file-
  14729.                                   area finding session.
  14730.               fileareaselect      Sets the user's current file area.
  14731.  
  14732.  
  14733.              15.2.13. File Tag Queue
  14734.  
  14735.              The functions listed in Table 15.25 are used to manipulate
  14736.              the queue of files to be downloaded.
  14737.  
  14738.              Table 15.25 File Tag Queue Functions
  14739.  
  14740.               Function            Description
  14741.  
  14742.  
  14743.  
  14744.              15. MEX Library Reference                                 268
  14745.  
  14746.               tag_dequeue_file    Removes a file from the tag queue.
  14747.               tag_get_name        Retrieves information about a file in
  14748.                                   the queue.
  14749.               tag_queue_file      Inserts a file in the queue.
  14750.               tag_queue_size      Returns the number of files in the
  14751.                                   queue.
  14752.  
  14753.  
  14754.              15.2.14. User File
  14755.  
  14756.              The functions listed in Table 15.26 are used to expand
  14757.              strings in user records, modify records in the user file, and
  14758.              to search the user file for selected records.
  14759.  
  14760.              Table 15.26 User File Functions
  14761.  
  14762.               Function                Description
  14763.  
  14764.               compressor_num_to_name  Converts the "usr.compress" field
  14765.                                       to a string.
  14766.               language_num_to_name    Converts the "usr.lang" field to a
  14767.                                       string.
  14768.               protocol_num_to_name    Converts the "usr.def_proto" field
  14769.                                       to a string.
  14770.               usercreate              Creates a new user record.
  14771.               userfilesize            Returns the size of the user file.
  14772.               userremove              Deletes a user record.
  14773.               userupdate              Updates an existing user record.
  14774.               userfindclose           Terminates a user-file finding
  14775.                                       session.
  14776.               userfindnext            Finds the next user record in a
  14777.                                       user-file finding session.
  14778.               userfindopen            Starts a user-file finding ses-
  14779.                                       sion.
  14780.               userfindprev            Finds the previous user record in
  14781.                                       a user-file finding session.
  14782.               userfindseek            Seeks to a specific user in a
  14783.                                       user-file finding session.
  14784.  
  14785.  
  14786.              15.2.15. Caller File Manipulation
  14787.  
  14788.              The functions listed in Table 15.27 are used to read the con-
  14789.              tents of the caller log file.
  14790.  
  14791.              Table 15.27 Caller File Functions
  14792.  
  14793.               Function        Description
  14794.  
  14795.               call_close      Closes the caller log file.
  14796.               call_numrecs    Returns the number of records in the
  14797.                               caller log file.
  14798.               call_open       Opens the caller log file.
  14799.  
  14800.  
  14801.  
  14802.              15. MEX Library Reference                                 269
  14803.  
  14804.               call_read       Reads from the caller log file.
  14805.  
  14806.  
  14807.              15.2.16. Log File
  14808.  
  14809.              The functions listed in Table 15.28 are used to append to the
  14810.              system log file.
  14811.  
  14812.              Table 15.28 Log File Functions
  14813.  
  14814.               Function   Description
  14815.  
  14816.               log        Adds a line to the system log.
  14817.  
  14818.  
  14819.              15.2.17. Maximus Control File Information
  14820.  
  14821.              The functions listed in Table 15.29 read from the Maximus
  14822.              .PRM file.
  14823.  
  14824.              Table 15.29 Control File Functions
  14825.  
  14826.               Function    Description
  14827.  
  14828.               prm_string  Returns a string from the MAX.PRM file.
  14829.  
  14830.  
  14831.              15.2.18. Privilege Level Information
  14832.  
  14833.              The functions listed in Table 15.30 return information about
  14834.              user classes (from the class definition file).
  14835.  
  14836.              Table 15.30 Privilege Level Functions
  14837.  
  14838.               Function            Description
  14839.  
  14840.               class_abbrev        Returns the abbreviation for a user
  14841.                                   class.
  14842.               class_info          Returns information about a user
  14843.                                   class.
  14844.               class_loginfile     Returns the login filename for a user
  14845.                                   class.
  14846.               class_name          Returns the name for a user class.
  14847.               class_to_priv       Converts a user class to a privilege
  14848.                                   level.
  14849.               privok              Checks if the user's access level sat-
  14850.                                   isfies a given ACS.
  14851.  
  14852.  
  14853.              15.2.19. Chat and Multinode Chat
  14854.  
  14855.              The functions listed in Table 15.31 provide a very limited
  14856.              interface to the system and multinode chat facilities.
  14857.  
  14858.  
  14859.  
  14860.              15. MEX Library Reference                                 270
  14861.  
  14862.              Table 15.31 Chat Functions
  14863.  
  14864.               Function           Description
  14865.  
  14866.               chat_querystatus   Query the multinode chat status of a
  14867.                                  user.
  14868.               chatstart          Enable local chat mode.
  14869.  
  14870.  
  14871.              15.2.20. Multilingual Support
  14872.  
  14873.              The functions listed in Table 15.32 allow strings to be re-
  14874.              trieved from the language file.
  14875.  
  14876.              Table 15.32 Multilingual Functions
  14877.  
  14878.               Function   Description
  14879.  
  14880.               hstr       Extract a string from a user language heap.
  14881.               lstr       Extract a string from the system language file.
  14882.  
  14883.  
  14884.              15.2.21. Static data
  14885.  
  14886.              The functions listed in Table 15.33 allow data to be created
  14887.              that stays "alive" for an entire Maximus session.
  14888.  
  14889.              Table 15.33 Static Data Functions
  14890.  
  14891.               Function               Description
  14892.  
  14893.               create_static_data     Creates a static data object.
  14894.               create_static_string   Creates a static string.
  14895.               destroy_static_data    Destroys a static data object.
  14896.               destroy_static_string  Destroys a static string.
  14897.               get_static_data        Gets information from a static data
  14898.                                      object.
  14899.               get_static_string      Gets information from a static
  14900.                                      string.
  14901.               set_static_data        Stores information in a static data
  14902.                                      object.
  14903.               set_static_string      Stores information in a static
  14904.                                      string.
  14905.  
  14906.  
  14907.              15.2.22. ANSI and RIPscrip Support
  14908.  
  14909.              The functions listed in Table 15.34 are used to query ANSI
  14910.              and RIPscrip support and to perform RIPscrip-specific file
  14911.              functions. (For information on sending ANSI or AVATAR cursor
  14912.              control codes to the user, instead see section 13.5.)
  14913.  
  14914.  
  14915.  
  14916.              15. MEX Library Reference                                 271
  14917.  
  14918.              Table 15.34 ANSI and RIPscrip Functions
  14919.  
  14920.               Function      Description
  14921.  
  14922.               ansi_detect   Determines if the user's terminal supports
  14923.                             ANSI.
  14924.               rip_detect    Determines if the user's terminal supports
  14925.                             RIPscrip.
  14926.               rip_hasfile   Determines if the user already has a spe-
  14927.                             cific RIPscrip scene or icon file.
  14928.               rip_send      Sends a RIPscrip file to the user.
  14929.  
  14930.  
  14931.  
  14932.              15. MEX Library Reference                                 272
  14933.  
  14934.  
  14935.              15.3. Function Descriptions
  14936.  
  14937.              This section contains detailed descriptions of all of the
  14938.              functions contained in the MEX run-time library.
  14939.  
  14940.              As a reminder, do not forget to include the following line at
  14941.              the beginning of any MEX source file that accesses the li-
  14942.              brary routines given in this section:
  14943.  
  14944.                 #include <max.mh>
  14945.  
  14946.  
  14947.              ansi_detect
  14948.  
  14949.  
  14950.  
  14951.  
  14952.  Prototype   int ansi_detect();
  14953.  
  14954.  Arguments   None
  14955.  
  14956.  Return Val. TRUE if the user's terminal supports ANSI; FALSE otherwise.
  14957.  
  14958.  Description The ansi_detect function is used to query the remote terminal
  14959.              to determine if it supports ANSI graphics. If the remote ter-
  14960.              minal reports that ANSI graphics are supported, this function
  14961.              returns TRUE.
  14962.  
  14963.              Note that some terminal programs may not support the control
  14964.              sequence used to query ANSI support. This means that this
  14965.              function may sometimes return FALSE, even if the user's ter-
  14966.              minal program does support ANSI. However, a return value of
  14967.              TRUE always indicates that the user's terminal supports ANSI.
  14968.  
  14969.              After the user has logged on, the user's ANSI graphics pref-
  14970.              erence can be read from the usr.video field.
  14971.  
  14972.  
  14973.  
  14974.              call_close
  14975.  
  14976.  
  14977.  
  14978.  
  14979.  Prototype   void call_close();
  14980.  
  14981.  Arguments   None
  14982.  
  14983.  Return Val. None
  14984.  
  14985.  Description This function releases the resources that were allocated to a
  14986.              MEX program by the call_open function. call_close should al-
  14987.  
  14988.  
  14989.  
  14990.              15. MEX Library Reference                                 273
  14991.  
  14992.              ways be called when the application is finished using the
  14993.              caller log.
  14994.  
  14995.  
  14996.  
  14997.              call_numrecs
  14998.  
  14999.  
  15000.  
  15001.  
  15002.  Prototype   long call_numrecs();
  15003.  
  15004.  Arguments   None
  15005.  
  15006.  Return Val. If the file was successful accessed, the number of records
  15007.              contained in the caller log;
  15008.              0 otherwise.
  15009.  
  15010.  Description The call_numrecs function enumerates the records in the
  15011.              caller log file. The call_read function can be used to read
  15012.              any of the records in the caller file, up to and including
  15013.              the record number returned by this function.
  15014.  
  15015.  
  15016.  
  15017.              call_open
  15018.  
  15019.  
  15020.  
  15021.  
  15022.  Prototype   int call_open();
  15023.  
  15024.  Arguments   None
  15025.  
  15026.  Return Val. TRUE if the caller file was opened successfully; FALSE other-
  15027.              wise.
  15028.  
  15029.  Description call_open is used to access the caller log, as defined by the
  15030.              File Callers keyword in the system control file.
  15031.  
  15032.              The caller log is different from the system log file, al-
  15033.              though both files contain similar information. While the sys-
  15034.              tem log file contains an ASCII listing of system events,
  15035.              meant to be read by humans, the caller log contains binary
  15036.              information that can be read by MEX programs and third-party
  15037.              utilities.
  15038.  
  15039.              The call_open function is used to obtain access to the caller
  15040.              log. After call_open has been called, any of the other call_*
  15041.              functions can be used to retrieve information from the caller
  15042.              log.
  15043.  
  15044.  
  15045.  
  15046.              15. MEX Library Reference                                 274
  15047.  
  15048.  
  15049.              call_read
  15050.  
  15051.  
  15052.  
  15053.  
  15054.  Prototype   int call_read(long: recno, ref struct _callinfo: ci);
  15055.  
  15056.  Arguments   recno The record number to be read from the caller log file.
  15057.              A value of 0 specifies the first record in the file. The
  15058.              range of valid record numbers can be determined by calling
  15059.              call_numrecs. In general, the range is from 0 to
  15060.              call_numrecs()-1 (inclusive).
  15061.  
  15062.              ci    The _callinfo structure into which the found record is
  15063.              to be placed.
  15064.  
  15065.  Return Val. TRUE if the record was successfully read; FALSE otherwise
  15066.  
  15067.  Description This function reads a record from the caller log file. The
  15068.              record specified by the recno parameter will be read from the
  15069.              caller log and placed into the structure referenced by the ci
  15070.              parameter.
  15071.  
  15072.              The _callinfo structure is defined in max.mh. A description
  15073.              of the fields in the structure can be found in the previous
  15074.              section.
  15075.  
  15076.  Example     A typical sequence of calls for accessing the caller file
  15077.              (without error-checking) is:
  15078.  
  15079.                 #include <max.mh>
  15080.  
  15081.                 int main()
  15082.                 {
  15083.                   struct _callinfo: ci;
  15084.                   long: num_recs;
  15085.                   int: i;
  15086.  
  15087.                   call_open();
  15088.                   num_recs := call_numrecs();
  15089.  
  15090.                   for (i := 0; i < num_recs; i := i+1)
  15091.                   {
  15092.                        call_read(i, ci);
  15093.                        // Process information in the "ci" structure
  15094.                   }
  15095.  
  15096.                   return 0;
  15097.                 }
  15098.  
  15099.  
  15100.  
  15101.              15. MEX Library Reference                                 275
  15102.  
  15103.  
  15104.              carrier
  15105.  
  15106.  
  15107.  
  15108.  
  15109.  Prototype   int carrier();
  15110.  
  15111.  Arguments   None
  15112.  
  15113.  Return Val. TRUE if DCD is present (high); FALSE if DCD is not present
  15114.              (low). This function always returns TRUE for local sessions.
  15115.  
  15116.  Description This function is used to sample the status of the modem DCD
  15117.              line. DCD is present if a caller is currently on-line.
  15118.  
  15119.              In most cases, DCD will always be present, since Maximus will
  15120.              normally recycle if a caller hangs up. However, if the auto-
  15121.              matic carrier-checking feature has been disabled with
  15122.              dcd_check, the carrier function can be used to manually check
  15123.              the status of the DCD line.
  15124.  
  15125.  
  15126.  
  15127.              chat_querystatus
  15128.  
  15129.  
  15130.  
  15131.  
  15132.  Prototype   int chat_querystatus(ref struct _cstat: cs);
  15133.  
  15134.  Arguments   cs    A reference to a caller status structure. On input, the
  15135.              cs.task_num field contains the task number whose status is to
  15136.              be queried. On output, the rest of the fields in the struc-
  15137.              ture will be updated to describe the status of the requested
  15138.              task.
  15139.  
  15140.  Return Val. TRUE if the status information was successfully read; FALSE
  15141.              if the task was not on-line, an invalid task number was
  15142.              specified, or if Maximus could not communicate with the chat
  15143.              server.
  15144.  
  15145.  Description This function is used to retrieve the status of an on-line
  15146.              user, including the user's name, status, and chat availabil-
  15147.              ity flag.
  15148.  
  15149.              Before calling chat_querystatus, the cs.task_num field should
  15150.              be filled out with the task number of the task to be queried.
  15151.  
  15152.              After the call, the cs structure will be filled out with all
  15153.              of the information about the requested task number.
  15154.  
  15155.  
  15156.  
  15157.              15. MEX Library Reference                                 276
  15158.  
  15159.  
  15160.              chatstart
  15161.  
  15162.  
  15163.  
  15164.  
  15165.  Prototype   void chatstart();
  15166.  
  15167.  Arguments   None
  15168.  
  15169.  Return Val. None
  15170.  
  15171.  Description The chatstart function is used to inform Maximus that the
  15172.              user is entering "chat" mode. This function is typically only
  15173.              used for MEX-based chat programs.
  15174.  
  15175.              When chat mode is in effect, the user's time limit is not
  15176.              decremented, and the "chat requested" flag on the status line
  15177.              is reset.
  15178.  
  15179.  
  15180.  
  15181.              class_abbrev
  15182.  
  15183.  
  15184.  
  15185.  
  15186.  Prototype   string class_abbrev(int: priv);
  15187.  
  15188.  Arguments   priv  The privilege level to be queried. This number can be
  15189.              in the range 0 through 65535.
  15190.  
  15191.  Return Val. A string indicating the name of the user class associated
  15192.              with the specified privilege level.
  15193.  
  15194.  Description This function is used to display a textual representation of
  15195.              a privilege level, rather than the numeric value of the
  15196.              privilege level itself. This function uses the information
  15197.              provided in the access control file to translate numeric
  15198.              privilege levels into strings.
  15199.  
  15200.  Example     If the standard privilege levels have not been modified, the
  15201.              following code will display "SysOp."  (100 is the privilege
  15202.              level of the SysOp class, as defined in the standard access
  15203.              control file.)
  15204.  
  15205.                 #include <max.mh>
  15206.  
  15207.                 int main()
  15208.                 {
  15209.                   string: s;
  15210.  
  15211.                   s := class_abbrev(100);
  15212.  
  15213.  
  15214.  
  15215.              15. MEX Library Reference                                 277
  15216.  
  15217.                   print(s);
  15218.  
  15219.                   return 0;
  15220.                 }
  15221.  
  15222.  
  15223.              class_info
  15224.  
  15225.  
  15226.  
  15227.  
  15228.  Prototype   long class_info(int: priv, int: cit);
  15229.  
  15230.  Arguments   priv  Privilege level which is to be queried.
  15231.  
  15232.              cit   One of the CIT_* constants describing the type of query
  15233.              to perform.
  15234.  
  15235.  Return Val. This function returns the requested value from the class in-
  15236.              formation structure, or -1 if an invalid value was specified
  15237.              for cit.
  15238.  
  15239.  Description This function is used to query a given privilege level for
  15240.              various types of information, such as its default time lim-
  15241.              its, download limits, and other miscellaneous values.
  15242.  
  15243.              Maximus first searches the definitions in the access control
  15244.              file to find the privilege class which is closest to (but
  15245.              which does not exceed) the privilege level specified by priv.
  15246.              It then returns the information requested by the cit parame-
  15247.              ter.
  15248.  
  15249.              The cit parameter can be any of the constants described in
  15250.              Table 15.35 below:
  15251.  
  15252.              Table 15.35 Class Information Types
  15253.  
  15254.               cit                  Description
  15255.  
  15256.               CIT_NUMCLASSES       If this value is specified, the priv
  15257.                                    parameter is ignored, and class_info
  15258.                                    returns the number of privilege level
  15259.                                    classes that are defined in the ac-
  15260.                                    cess control file.
  15261.               CIT_DAY_TIME         The maximum daily time limit.
  15262.               CIT_CALL_TIME        The maximum per-connection time
  15263.                                    limit.
  15264.               CIT_DL_LIMIT         The daily download limit, in kilo-
  15265.                                    bytes.
  15266.               CIT_RATIO            The maximum download : upload ratio.
  15267.               CIT_MIN_BAUD         The minimum speed required to log on.
  15268.               CIT_MIN_XFER_BAUD    The minimum speed required to down-
  15269.                                    load or upload files.
  15270.  
  15271.  
  15272.  
  15273.              15. MEX Library Reference                                 278
  15274.  
  15275.               CIT_MAX_CALLS        The maximum number of times that a
  15276.                                    user can call in a given day.
  15277.               CIT_FREE_RATIO       The number of kilobytes that can be
  15278.                                    downloaded before the download ratio
  15279.                                    takes effect.
  15280.               CIT_UPLOAD_REWARD    Percentage of the user's time re-
  15281.                                    warded for uploading files.
  15282.               CIT_ACCESSFLAGS      User access flags, as defined in the
  15283.                                    access control file. See the CFLAGA_*
  15284.                                    definitions in max.mh for more infor-
  15285.                                    mation.
  15286.               CIT_MAILFLAGS        User mail capability flags, as de-
  15287.                                    fined in the access control file. See
  15288.                                    the CFLAGM_* definitions in max.mh
  15289.                                    for more information.
  15290.               CIT_USERFLAGS        User-specific flags, which were spe-
  15291.                                    cifically designed for use by MEX
  15292.                                    programs. See the documentation for
  15293.                                    these flags in the access control
  15294.                                    file for more information.
  15295.               CIT_LEVEL            The numeric privilege level associ-
  15296.                                    ated with this class. Since Maximus
  15297.                                    retrieves the class with the privi-
  15298.                                    lege level closest to (but not ex-
  15299.                                    ceeding) the priv parameter, the
  15300.                                    value returned by this function will
  15301.                                    not necessarily be the same as the
  15302.                                    value provided for priv.
  15303.               CIT_CLASSKEY         The "key" associated with the class.
  15304.                                    This is normally the first letter of
  15305.                                    the class abbreviation, but it can be
  15306.                                    changed manually by the SysOp.
  15307.               CIT_INDEX            The "index number" of the specified
  15308.                                    privilege level.
  15309.               CIT_OLDPRIV          The old-style Maximus 2.x privilege
  15310.                                    level that corresponds to priv. This
  15311.                                    can be used when writing programs to
  15312.                                    manipulate data structures that are
  15313.                                    used by external programs designed to
  15314.                                    work with Maximus 2.x.
  15315.               CIT_BYINDEX          If this value is combined with any of
  15316.                                    the CIT_ parameters above (using the
  15317.                                    bitwise or operator), the value of
  15318.                                    priv is assumed to be a class index
  15319.                                    rather than a privilege level.
  15320.  
  15321.  
  15322.              This code displays the maximum daily time limit for the cur-
  15323.              rent user:
  15324.  
  15325.                 #include <max.mh>
  15326.  
  15327.                 int main()
  15328.  
  15329.  
  15330.  
  15331.              15. MEX Library Reference                                 279
  15332.  
  15333.                 {
  15334.                   long: lim;
  15335.  
  15336.                   lim := class_info(usr.priv, CIT_DAY_TIME);
  15337.                   print("Maximum daily limit: ", lim, " minutes.\n");
  15338.  
  15339.                   return 0;
  15340.                 }
  15341.  
  15342.              The following code can be used to iterate through all of the
  15343.              class definitions in the access control file:
  15344.  
  15345.                 #include <max.mh>
  15346.  
  15347.                 int main()
  15348.                 {
  15349.                   int: i, n;
  15350.                   unsigned int: priv;
  15351.  
  15352.                   n := class_info(0, CIT_NUMCLASSES);
  15353.  
  15354.                   for (i := 0; i < n; i := i+1)
  15355.                   {
  15356.                        priv := class_info(i,
  15357.                                           CIT_LEVEL | CIT_BYINDEX);
  15358.                        print("Priv for class ", i, " is ",
  15359.                              priv, '\n');
  15360.                   }
  15361.  
  15362.                   return 0;
  15363.                 }
  15364.  
  15365.  
  15366.              class_loginfile
  15367.  
  15368.  
  15369.  
  15370.  
  15371.  Prototype   string class_loginfile(int: priv);
  15372.  
  15373.  Arguments   priv  The privilege level to be queried
  15374.  
  15375.  Return Val. A string representing the log-in file specific to callers in
  15376.              this privilege level. The null string ("") is returned if no
  15377.              log-in file is defined for the requested privilege level.
  15378.  
  15379.  Description This function is used to retrieve the name of the custom log-
  15380.              in file for members of a specific privilege level. The custom
  15381.              log-in file is typically used to display information that
  15382.              only pertains to a specific group of users.
  15383.  
  15384.  
  15385.  
  15386.              15. MEX Library Reference                                 280
  15387.  
  15388.              While Maximus will normally display this file automatically
  15389.              at log-on, MEX programs can also use this information to dis-
  15390.              play the file manually.
  15391.  
  15392.  Example     This code will display the custom log-on file for the current
  15393.              user:
  15394.  
  15395.                 #include <max.mh>
  15396.  
  15397.                 int main()
  15398.                 {
  15399.                   string: file;
  15400.                   char: nonstop;
  15401.  
  15402.                   file := class_loginfile(usr.priv);
  15403.                   nonstop := 0;
  15404.  
  15405.                   if (file <> "")
  15406.                        display_file(file, nonstop);
  15407.  
  15408.                   return 0;
  15409.                 }
  15410.  
  15411.  
  15412.              class_name
  15413.  
  15414.  
  15415.  
  15416.  
  15417.  Prototype   string class_name(int: priv);
  15418.  
  15419.  Arguments   priv  The privilege level to be queried
  15420.  
  15421.  Return Val. A string containing the name of the privilege level.
  15422.  
  15423.  Description This function is used to obtain the description for a spe-
  15424.              cific privilege level from the access control file.
  15425.  
  15426.  
  15427.  
  15428.              class_to_priv
  15429.  
  15430.  
  15431.  
  15432.  
  15433.  Prototype   unsigned int class_to_priv(string: classabbrev);
  15434.  
  15435.  Arguments   classabbrev    A string containing an abbreviation for a
  15436.              class privilege level.
  15437.  
  15438.  Return Val. The numeric privilege level associated with the name, or
  15439.              65535 if the name could not be matched to any existing class.
  15440.  
  15441.  
  15442.  
  15443.              15. MEX Library Reference                                 281
  15444.  
  15445.  Description This function is used to translate text-based privilege level
  15446.              names into numeric privilege level values, such as those
  15447.              stored in many of the internal Maximus structures.
  15448.  
  15449.  
  15450.  
  15451.              close
  15452.  
  15453.  
  15454.  
  15455.  
  15456.  Prototype   int close(int fd)
  15457.  
  15458.  Arguments   fd     A file handle previously returned by open.
  15459.  
  15460.  Return Val. TRUE if the file was successfully closed; FALSE otherwise.
  15461.  
  15462.  Description This function is used to close a file handle that was previ-
  15463.              ously opened by open. MEX programs should close file handles
  15464.              as soon as all file operations on that handle have been com-
  15465.              pleted.
  15466.  
  15467.  
  15468.  
  15469.              compressor_num_to_name
  15470.  
  15471.  
  15472.  
  15473.  
  15474.  Prototype   string compressor_num_to_name(int: compressor);
  15475.  
  15476.  Arguments   compressor     An integer index for a compression program in
  15477.              compress.cfg.
  15478.  
  15479.  Return Val. A string containing the name of the compressor, or the null
  15480.              string ("") if the compressor index is invalid.
  15481.  
  15482.  Description This function is used to translate the usr.compress field in
  15483.              the user structure to obtain a human-readable string.
  15484.  
  15485.  
  15486.  
  15487.              create_static_data
  15488.  
  15489.  
  15490.  
  15491.  
  15492.  Prototype   int create_static_data(string: key, long: size);
  15493.  
  15494.  Arguments   key   A string containing a used-defined key. This key iden-
  15495.              tifies the data item to be created. This string must be used
  15496.              to identify this data item in all future calls to the
  15497.  
  15498.  
  15499.  
  15500.              15. MEX Library Reference                                 282
  15501.  
  15502.              *_static_data functions. The recommended format for the key
  15503.              string is:
  15504.  
  15505.                    "program_name : program_specific_value", where pro-
  15506.                    gram_name is the name of the MEX program being exe-
  15507.                    cuted, and program_specific_value is a brief descrip-
  15508.                    tion of the item to be stored.
  15509.  
  15510.              size  The size of the data object to be created. The value
  15511.              used for this parameter is normally obtained by using the
  15512.              sizeof operator on the type of the object to be stored.
  15513.  
  15514.  Return Val. 0 if the data object was created successfully;
  15515.              -1 if not enough memory was available to satisfy the request;
  15516.              -2 if an invalid parameter was specified;
  15517.              -3 if the key name already exists.
  15518.  
  15519.  Description Normal MEX variables are destroyed as soon as the calling MEX
  15520.              program returns to Maximus, but the create_static_data func-
  15521.              tion allows programs to create persistent data  objects that
  15522.              remain around for an entire Maximus session.
  15523.  
  15524.              This function is used to store integral data types (char, int
  15525.              and long) and aggregates (user-defined struct and array
  15526.              types). To manipulate strings, see create_static_string.
  15527.  
  15528.              The size parameter should indicate the size of the data to be
  15529.              stored within the static data object. The sizeof operator is
  15530.              normally used to calculate this value. For example, if a long
  15531.              is to be stored, size should be set to sizeof(long).
  15532.  
  15533.              Static data objects created by create_static_data are ini-
  15534.              tially set to binary zeroes.
  15535.  
  15536.  Example     The following code demonstrates how to create a static data
  15537.              object called "myfoo" from test.mex. The data object is large
  15538.              enough to hold a "foo" structure:
  15539.  
  15540.                 struct foo
  15541.                 {
  15542.                   int: bar;
  15543.                   int: boz;
  15544.                 };
  15545.  
  15546.                 // ...
  15547.  
  15548.                 struct foo: myfoo;
  15549.  
  15550.                 create_static_data("test:current_foo",
  15551.                                    sizeof(struct foo));
  15552.  
  15553.  
  15554.  
  15555.              15. MEX Library Reference                                 283
  15556.  
  15557.  
  15558.              create_static_string
  15559.  
  15560.  
  15561.  
  15562.  
  15563.  Prototype   int create_static_string(string: key);
  15564.  
  15565.  Arguments   key   A string containing a used-defined key. This key is
  15566.              used to identify the data item to be created. This string
  15567.              must be used to identify this data item to all future calls
  15568.              to the *_static_data functions. The recommended format for
  15569.              the key string is:
  15570.  
  15571.                     "program_name : program_specific_value", where pro-
  15572.                    gram_name is the name of the MEX program being exe-
  15573.                    cuted, and program_specific_value is a brief descrip-
  15574.                    tion of the string to be stored.
  15575.  
  15576.  Return Val. 0 if the string was created successfully;
  15577.              -1 if not enough memory was available to satisfy the request;
  15578.              -2 if an invalid parameter was specified;
  15579.              -3 if the key name already exists.
  15580.  
  15581.  Description This function is similar to create_static_data, except that
  15582.              it creates persistent string variables. Maximus will manage
  15583.              the string size internally, so no size parameter is required
  15584.              for create_static_string.
  15585.  
  15586.              A string created by create_static_string is initially empty.
  15587.  
  15588.              For more information, see the description for cre-
  15589.              ate_static_data.
  15590.  
  15591.  Example     This code shows how to create a static string called
  15592.              "mystring" from test.mex:
  15593.  
  15594.                 create_static_string("test:mystring");
  15595.  
  15596.  
  15597.              dcd_check
  15598.  
  15599.  
  15600.  
  15601.  
  15602.  Prototype   int dcd_check(int: state);
  15603.  
  15604.  Arguments   state A flag indicating whether or not DCD checking is to be
  15605.              used. If non-zero, DCD checking is performed. If zero, DCD
  15606.              checking is not performed.
  15607.  
  15608.  Return Val. An integer describing the prior state of DCD checking. A
  15609.              value of 1 indicates that DCD checking was previously being
  15610.  
  15611.  
  15612.  
  15613.              15. MEX Library Reference                                 284
  15614.  
  15615.              performed; a value of 0 indicates that DCD checking was not
  15616.              being performed.
  15617.  
  15618.  Description This function is used to control whether or not Maximus
  15619.              checks the DCD line. Normally, the absence of DCD indicates
  15620.              that the caller has hung up. However, some special MEX pro-
  15621.              grams may wish to ignore this signal, such as in call-back
  15622.              verifier programs.
  15623.  
  15624.              When automatic DCD checking is off, the carrier function can
  15625.              be used to manually check for DCD.
  15626.  
  15627.  
  15628.  
  15629.              destroy_static_data
  15630.  
  15631.  
  15632.  
  15633.  
  15634.  Prototype   int destroy_static_data(string: key);
  15635.  
  15636.  Arguments   key   The key for the static data object to be destroyed.
  15637.              This must be the same as the key parameter passed to cre-
  15638.              ate_static_data.
  15639.  
  15640.  Return Val. 0 if the data object was destroyed successfully;
  15641.              -1 if the key name was not found
  15642.  
  15643.  Description This function destroys a static object key and the corre-
  15644.              sponding object data, and it then returns the associated mem-
  15645.              ory to Maximus. This code must be called whenever a static
  15646.              data object is no longer required.
  15647.  
  15648.  Example     To destroy the static data object that was created in the ex-
  15649.              ample for the create_static_data function:
  15650.  
  15651.                 destroy_static_data("test:current_foo");
  15652.  
  15653.  
  15654.              destroy_static_string
  15655.  
  15656.  
  15657.  
  15658.  
  15659.  Prototype   int destroy_static_string(string: key);
  15660.  
  15661.  Arguments   key   The key for the static string to be destroyed. This
  15662.              must be the same as the key parameter passed to cre-
  15663.              ate_static_string.
  15664.  
  15665.  Return Val. 0 if the string was destroyed successfully;
  15666.              -1 if the key name was not found
  15667.  
  15668.  
  15669.  
  15670.              15. MEX Library Reference                                 285
  15671.  
  15672.  Description This function destroys a static string key and the corre-
  15673.              sponding string data, and it then returns the associated mem-
  15674.              ory to Maximus. This code must be called whenever a static
  15675.              string is no longer required.
  15676.  
  15677.  Example     To destroy the static string that was created in the example
  15678.              for the create_static_string function:
  15679.  
  15680.                 destroy_static_string("test:mystring");
  15681.  
  15682.  
  15683.              display_file
  15684.  
  15685.  
  15686.  
  15687.  
  15688.  Prototype   int display_file(string: filename, ref char: nonstop);
  15689.  
  15690.  Arguments   filename  The name of the .bbs file to be displayed to the
  15691.              user. If no extension is provided, ".bbs" is assumed.
  15692.  
  15693.                    WARNING!
  15694.  
  15695.                    All backslashes must be escaped in MEX programs. For
  15696.                    example, to specify a file called \max\misc\foo.bbs,
  15697.                    the parameter must contain "\\max\\misc\\foo.bbs".
  15698.  
  15699.              nonstop   A reference to a variable used for controlling non-
  15700.              stop display action. See the description and examples below
  15701.              for more information.
  15702.  
  15703.  Return Val. 0 if the file was displayed successfully;
  15704.              -1 otherwise.
  15705.  
  15706.  Description This function is used to display a .bbs file from within a
  15707.              MEX program. Any .bbs file can be displayed, as long as it
  15708.              does not try to recursively call another MEX program.
  15709.  
  15710.              The nonstop parameter is used to control non-stop file dis-
  15711.              play. In most cases, this variable should be initialized to 0
  15712.              before calling display_file and then left alone.
  15713.  
  15714.              If nonstop is set to 0 before calling display_file, normal
  15715.              "More" processing will take effect. Maximus will prompt the
  15716.              user with "More [Y,n,=]"  after every page of information has
  15717.              been displayed. If the user selects "=" at a More prompt, the
  15718.              nonstop parameter will be updated with a value of 1.
  15719.  
  15720.              If nonstop is set to 1 before calling display_file, Maximus
  15721.              will assume that the user already asked for non-stop display,
  15722.              so it will not prompt the user after every page.
  15723.  
  15724.  
  15725.  
  15726.              15. MEX Library Reference                                 286
  15727.  
  15728.              The nonstop variable can be used to implement the non-stop
  15729.              display of multiple files at a time.
  15730.  
  15731.  Example     This code shows how to display a single file:
  15732.  
  15733.                 #include <max.mh>
  15734.  
  15735.                 int main()
  15736.                 {
  15737.                   char: nonstop;
  15738.  
  15739.                   nonstop := 0;
  15740.                   display_file("c:\\max\\misc\\logo.bbs", nonstop);
  15741.  
  15742.                   return 0;
  15743.                 }
  15744.  
  15745.              This code shows how to display multiple files in succession,
  15746.              allowing for continuous display:
  15747.  
  15748.                 #include <max.mh>
  15749.  
  15750.                 int main()
  15751.                 {
  15752.                   char: nonstop;
  15753.  
  15754.                   nonstop := 0;     // only initialize to 0 for
  15755.                                     // the first display
  15756.  
  15757.                   display_file("c:\\max\\misc\\logo.bbs", nonstop);
  15758.                   display_file("c:\\max\\misc\\welcome.bbs",
  15759.                                nonstop);
  15760.  
  15761.                   return 0;
  15762.                 }
  15763.  
  15764.              The above code would display c:\max\misc\logo.bbs to the
  15765.              user, followed by c:\max\misc\welcome.bbs. If the user re-
  15766.              quested non-stop output while displaying logo.bbs, the wel-
  15767.              come.bbs file would also be displayed in non-stop mode. If
  15768.              this is not desired, nonstop should be set to 0 before each
  15769.              call to display_file.
  15770.  
  15771.  
  15772.  
  15773.              do_more
  15774.  
  15775.  
  15776.  
  15777.  
  15778.  Prototype   int do_more(ref char: nonstop, string: color);
  15779.  
  15780.  
  15781.  
  15782.              15. MEX Library Reference                                 287
  15783.  
  15784.  Arguments   nonstop   A reference to a variable used to store the non-
  15785.              stop display status. This variable is normally initialized by
  15786.              a call to the reset_more function.
  15787.  
  15788.              color A string containing the color to be used for displaying
  15789.              the More prompt. (This is normally one of the COL_* constants
  15790.              from mex.mh.)
  15791.  
  15792.  Return Val. TRUE if less than a page of information has been displayed
  15793.              since the last reset_more call, if the user answered "yes"
  15794.              or "=" at the prompt displayed by do_more, or if non-stop
  15795.              display is in effect; FALSE otherwise.
  15796.  
  15797.  Description This function is used to display "More [Y,n,=]" prompts to
  15798.              the user in appropriate places. This is useful when display-
  15799.              ing a long list of information that is longer than one
  15800.              screen.
  15801.  
  15802.              The do_more function keeps track of the number of lines that
  15803.              have been displayed since the last reset_more call. If the
  15804.              line count is less than the length of the screen, do_more
  15805.              will do nothing and return TRUE.
  15806.  
  15807.              If the line count is greater than or equal to the length of
  15808.              the screen, do_more will display a "More [Y,n,=]" prompt and
  15809.              reset the displayed line count, as long as the nonstop vari-
  15810.              able has a value of 0:
  15811.  
  15812.              If the user answers "N" at the prompt, do_more will return
  15813.              FALSE.
  15814.  
  15815.              If the user answers "Y" at the prompt, do_more will return
  15816.              TRUE.
  15817.  
  15818.              If the user answers "=" at the prompt, do_more will return
  15819.              TRUE and set the value of nonstop to 1.
  15820.  
  15821.              However, do_more will not display a More prompt to the user
  15822.              if the nonstop variable contains a value of 1 upon entry to
  15823.              the do_more function.
  15824.  
  15825.              For a final special case, if the nonstop variable has a value
  15826.              of -1, do_more  will always prompt the user for more, as in
  15827.              the case where nonstop was 0, as above. However, the value of
  15828.              nonstop will never be changed. Consequently, setting nonstop
  15829.              to -1 ensures that the More prompt will be displayed to the
  15830.              user after every page, even if the user specifically selects
  15831.              the "=" option.
  15832.  
  15833.  Example     For example, to display output with paging support provided
  15834.              by the do_more function:
  15835.  
  15836.                 #include <max.mh>
  15837.  
  15838.  
  15839.  
  15840.              15. MEX Library Reference                                 288
  15841.  
  15842.  
  15843.                 int main()
  15844.                 {
  15845.                   int: line;
  15846.                   int: done;
  15847.                   char: nonstop;
  15848.  
  15849.                   reset_more(nonstop);
  15850.                   done := 0;
  15851.  
  15852.                   for (line := 1;
  15853.                        line <= 100 and done=0;
  15854.                        line := line + 1)
  15855.                   {
  15856.                        print("Line #", line, '\n');
  15857.  
  15858.                        if (do_more(nonstop, COL_WHITE) = 0)
  15859.                             done := TRUE;
  15860.                   }
  15861.  
  15862.                   return 0;
  15863.                 }
  15864.  
  15865.  
  15866.              file_area
  15867.  
  15868.  
  15869.  
  15870.  
  15871.  Prototype   void file_area();
  15872.  
  15873.  Arguments   None
  15874.  
  15875.  Return Val. None
  15876.  
  15877.  Description This function displays the file area menu. Calling file_area
  15878.              is equivalent to calling menu_cmd(MNU_FILE_AREA, ""), al-
  15879.              though calling file_area is slightly faster.
  15880.  
  15881.  
  15882.  
  15883.              fileareafindclose
  15884.  
  15885.  
  15886.  
  15887.  
  15888.  Prototype   void fileareafindclose();
  15889.  
  15890.  Arguments   None
  15891.  
  15892.  Return Val. None
  15893.  
  15894.  
  15895.  
  15896.              15. MEX Library Reference                                 289
  15897.  
  15898.  Description The fileareafindclose function terminates an existing
  15899.              fileareafindfirst search. This function should be called
  15900.              whenever the program has finished using the file area data
  15901.              file.
  15902.  
  15903.  
  15904.  
  15905.              fileareafindfirst
  15906.  
  15907.  
  15908.  
  15909.  
  15910.  Prototype   int fileareafindfirst(ref struct _farea: fa, string: name,
  15911.              int: flags);
  15912.  
  15913.  Arguments   fa    A reference to a file area information structure. If
  15914.              this function finds a file area matching the name and flags
  15915.              parameters, information about that file area will be placed
  15916.              in this structure.
  15917.  
  15918.              name  Name of a specific file area to find. If name is the
  15919.              null string (""), this function will find the first available
  15920.              file area.
  15921.  
  15922.              flags A flag indicating whether or not FileDivisionBegin and
  15923.              FileDivisionEnd records are to be returned. If this flag is
  15924.              equal to AFFO_DIV, division records will be returned. Other-
  15925.              wise, if this flag is equal to AFFO_NODIV, division records
  15926.              will be skipped.
  15927.  
  15928.  Return Val. TRUE if an area was found; FALSE otherwise.
  15929.  
  15930.  Description The fileareafindfirst function searches for a specific file
  15931.              area, as specified by the name parameter. It also finds divi-
  15932.              sion records within the area file if the AFFO_DIV flag is
  15933.              specified.
  15934.  
  15935.              Only areas which can be accessed by the user will be returned
  15936.              by this function. This function will also skip file areas
  15937.              that have the Type Hidden style.
  15938.  
  15939.  Example     The following code will display a list of all file areas:
  15940.  
  15941.                 #include <max.mh>
  15942.  
  15943.                 int main()
  15944.                 {
  15945.                   struct _farea: fa;
  15946.  
  15947.                   if (fileareafindfirst(fa, "", AFFO_NODIV))
  15948.                   {
  15949.                        do
  15950.                        {
  15951.  
  15952.  
  15953.  
  15954.              15. MEX Library Reference                                 290
  15955.  
  15956.                             print("Area: ", fa.name, '\n');
  15957.                        }
  15958.                        while (fileareafindnext(fa));
  15959.  
  15960.                        fileareafindclose();
  15961.                   }
  15962.  
  15963.                   return 0;
  15964.                 }
  15965.  
  15966.  
  15967.              fileareafindnext
  15968.  
  15969.  
  15970.  
  15971.  
  15972.  Prototype   int fileareafindnext(ref struct _farea: fa);
  15973.  
  15974.  Arguments   fa    A reference to the file area structure to be updated
  15975.              with file area information. This structure must have been
  15976.              originally filled in by a fileareafindfirst, fileareaf-
  15977.              indnext, or fileareafindprev call.
  15978.  
  15979.  Return Val. TRUE if another file area was found; FALSE if no file area
  15980.              could be found.
  15981.  
  15982.  Description The fileareafindnext function finds the next file area that
  15983.              is accessible to the user. The search is carried out from the
  15984.              position where the last fileareafindnext, fileareafindprev,
  15985.              or fileareafindfirst call terminated. Consequently, if the
  15986.              last fileareafind* call returned information for area "X",
  15987.              this function would return information for the next user-
  15988.              accessible area following area "X".
  15989.  
  15990.  
  15991.  
  15992.              fileareafindprev
  15993.  
  15994.  
  15995.  
  15996.  
  15997.  Prototype   int fileareafindprev(ref struct _farea: fa);
  15998.  
  15999.  Arguments   fa    A reference to the file area structure to be updated
  16000.              with file area information. This structure must have been
  16001.              originally filled in by a fileareafindfirst, fileareaf-
  16002.              indnext, or fileareafindprev call.
  16003.  
  16004.  Return Val. TRUE if another file area was found; FALSE if no file area
  16005.              could be found.
  16006.  
  16007.  Description The fileareafindprev function finds the previous file area
  16008.              that is accessible to the user. The search is carried out
  16009.  
  16010.  
  16011.  
  16012.              15. MEX Library Reference                                 291
  16013.  
  16014.              from the position where the last fileareafindnext, fileareaf-
  16015.              indprev, or fileareafindfirst call terminated. Consequently,
  16016.              if the last fileareafind* call returned information for area
  16017.              "X", this function would return information for the first
  16018.              user-accessible area that precedes area "X".
  16019.  
  16020.  
  16021.  
  16022.              fileareaselect
  16023.  
  16024.  
  16025.  
  16026.  
  16027.  Prototype   int fileareaselect(string: name);
  16028.  
  16029.  Arguments   name  Name of the file area to be selected as the user's cur-
  16030.              rent file area.
  16031.  
  16032.  Return Val. TRUE if the area was successfully selected; FALSE otherwise.
  16033.  
  16034.  Description The fileareaselect function is used to change the user's cur-
  16035.              rent file area. Upon return, this function also updates the
  16036.              global farea variable with information about the new file
  16037.              area.
  16038.  
  16039.  
  16040.  
  16041.              filecopy
  16042.  
  16043.  
  16044.  
  16045.  
  16046.  Prototype   int filecopy(string: old, string: new);
  16047.  
  16048.  Arguments   old   Name of the file to be copied.
  16049.  
  16050.                    WARNING!
  16051.  
  16052.                    All backslashes must be escaped in MEX programs. For
  16053.                    example, to specify a file called \max\misc\foo.bbs,
  16054.                    the parameter must contain "\\max\\misc\\foo.bbs".
  16055.  
  16056.              new   Target path and filename for the copy.
  16057.  
  16058.  Return Val. TRUE if the file was successfully copied; FALSE otherwise.
  16059.  
  16060.  Description This function copies a file from old to new.
  16061.  
  16062.  
  16063.  
  16064.              15. MEX Library Reference                                 292
  16065.  
  16066.  
  16067.              filedate
  16068.  
  16069.  
  16070.  
  16071.  
  16072.  Prototype   int filedate(string: filename, ref struct stamp: fdate);
  16073.  
  16074.  Arguments   filename  The name of the file to be queried.
  16075.  
  16076.                    WARNING!
  16077.  
  16078.                    All backslashes must be escaped in MEX programs. For
  16079.                    example, to specify a file called \max\misc\foo.bbs,
  16080.                    the parameter must contain "\\max\\misc\\foo.bbs".
  16081.  
  16082.              fdate A reference to a stamp structure that will be updated
  16083.              to contain information about the file's date.
  16084.  
  16085.  Return Val. This function returns TRUE if the file date was successfully
  16086.              obtained; FALSE otherwise.
  16087.  
  16088.  Description The filedate function is used to obtain the last-write date
  16089.              for a specific file.
  16090.  
  16091.  
  16092.  
  16093.              fileexists
  16094.  
  16095.  
  16096.  
  16097.  
  16098.  Prototype   int fileexists(string: filename);
  16099.  
  16100.  Arguments   filename  The name of the file to be queried.
  16101.  
  16102.                    WARNING!
  16103.  
  16104.                    All backslashes must be escaped in MEX programs. For
  16105.                    example, to specify a file called \max\misc\foo.bbs,
  16106.                    the parameter must contain "\\max\\misc\\foo.bbs".
  16107.  
  16108.  Return Val. TRUE if the file exists; FALSE otherwise.
  16109.  
  16110.  Description This function is used to determine whether or not the speci-
  16111.              fied file exists on disk.
  16112.  
  16113.  
  16114.  
  16115.              15. MEX Library Reference                                 293
  16116.  
  16117.  
  16118.              filefindclose
  16119.  
  16120.  
  16121.  
  16122.  
  16123.  Prototype   void filefindclose(ref struct _ffind: ff);
  16124.  
  16125.  Arguments   ff    A reference to the _ffind structure that was returned
  16126.              by a previous call to filefindfirst.
  16127.  
  16128.  Return Val. None
  16129.  
  16130.  Description This function releases the system resources that were allo-
  16131.              cated when performing a filefindfirst call.
  16132.  
  16133.  
  16134.  
  16135.              filefindfirst
  16136.  
  16137.  
  16138.  
  16139.  
  16140.  Prototype   int filefindfirst(ref struct _ffind: ff, string: filename,
  16141.              int: attribs);
  16142.  
  16143.  Arguments   ff    A reference to a _ffind structure to be updated by this
  16144.              function. Upon return, this structure is updated with infor-
  16145.              mation about the file found (if any).
  16146.  
  16147.              filename  A wildcard specification (or individual filename)
  16148.              for which this function is to search.
  16149.  
  16150.              attribs   A set of  attributes used to describe the types of
  16151.              files to find. This should be FA_NORMAL in most cases, but it
  16152.              can also be one or more of the following, connected using the
  16153.              bitwise or operator: FA_READONLY, FA_HIDDEN, FA_SYSTEM,
  16154.              FA_VOLUME, FA_SUBDIR, or FA_ARCHIVE. This mask restricts the
  16155.              filenames returned to those which have the specified attrib-
  16156.              utes.
  16157.  
  16158.  Return Val. TRUE if a file was successfully found; FALSE otherwise.
  16159.  
  16160.  Description This function is normally used to expand file or directory
  16161.              wildcards. Given a filename specification such as "A*.*", the
  16162.              filefindfirst function will search for the specified file us-
  16163.              ing the host operating system.
  16164.  
  16165.              The first file matching filename will be returned in the ff
  16166.              structure, including information about the file's name, size,
  16167.              date and attributes.  (However, for finding file information
  16168.              for a single, non-wildcard filename, the filesize and fileex-
  16169.              ists functions are generally much faster.)
  16170.  
  16171.  
  16172.  
  16173.              15. MEX Library Reference                                 294
  16174.  
  16175.              To find the second and subsequent files that match the speci-
  16176.              fied wildcard, see the filefindnext function.
  16177.  
  16178.  Example     This code displays all of the files in the current directory:
  16179.  
  16180.                 #include <max.mh>
  16181.  
  16182.                 int main()
  16183.                 {
  16184.                   struct _ffind: ff;
  16185.  
  16186.                   if (filefindfirst(ff, "*.*", FA_NORMAL))
  16187.                   {
  16188.                        do
  16189.                        {
  16190.                             print("Found file: ",
  16191.                                   ff.filename, '\n');
  16192.                        }
  16193.                        while (filefindnext(ff));
  16194.  
  16195.                        filefindclose(ff);
  16196.                   }
  16197.  
  16198.                   return 0;
  16199.                 }
  16200.  
  16201.  
  16202.              filefindnext
  16203.  
  16204.  
  16205.  
  16206.  
  16207.  Prototype   int filefindnext(ref struct _ffind: ff);
  16208.  
  16209.  Arguments   ff    A reference to the _ffind structure that was returned
  16210.              by a previous call to filefindfirst.
  16211.  
  16212.  Return Val. TRUE if another file was found; FALSE otherwise.
  16213.  
  16214.  Description The filefindnext function continues a search that was started
  16215.              by filefindfirst.  This function returns the next filename
  16216.              matching the pattern specified in the original filefindfirst
  16217.              call.
  16218.  
  16219.  
  16220.  
  16221.              filesize
  16222.  
  16223.  
  16224.  
  16225.  
  16226.  Prototype   long filesize(string: filename);
  16227.  
  16228.  
  16229.  
  16230.              15. MEX Library Reference                                 295
  16231.  
  16232.  Arguments   filename  The filename whose size is to be queried.
  16233.  
  16234.                    WARNING!
  16235.  
  16236.                    All backslashes must be escaped in MEX programs. For
  16237.                    example, to specify a file called \max\misc\foo.bbs,
  16238.                    the parameter must contain "\\max\\misc\\foo.bbs".
  16239.  
  16240.  Return Val. -1 if the file does not exist; otherwise, this function re-
  16241.              turns the file size.
  16242.  
  16243.  Description The filesize function is used to retrieve the size of a file.
  16244.  
  16245.  
  16246.  
  16247.              get_static_data
  16248.  
  16249.  
  16250.  
  16251.  
  16252.  Prototype   int get_static_data(string: key, ref void: data);
  16253.  
  16254.  Arguments   key   The key for the static data object to be retrieved.
  16255.              This must be the same as the key parameter originally passed
  16256.              to create_static_data.
  16257.  
  16258.              data  A reference to the local data object that is to be up-
  16259.              dated with a copy of the static data object. Note that this
  16260.              parameter is a void reference, meaning that any type of ob-
  16261.              ject (char, int, long, array or struct) can be referenced.
  16262.  
  16263.  Return Val. 0 if the data object was retrieved successfully;
  16264.              -1 if the key name was not found.
  16265.  
  16266.  Description The get_static_data function is used to retrieve data that
  16267.              was previously stored by the set_static_data function. If key
  16268.              is a valid static data key that was created by cre-
  16269.              ate_static_data, this function will retrieve the information
  16270.              in the static data object and copy it into the local variable
  16271.              referenced by data.
  16272.  
  16273.  Example     The following code creates a static data object, writes a
  16274.              value to it, and then retrieves it again (without error
  16275.              checking):
  16276.  
  16277.                 #include <max.mh>
  16278.  
  16279.                 int main()
  16280.                 {
  16281.                   long: l1, l2;
  16282.                   string: dataname;
  16283.  
  16284.                   dataname := "test:mylong";
  16285.  
  16286.  
  16287.  
  16288.              15. MEX Library Reference                                 296
  16289.  
  16290.                   create_static_data(dataname, sizeof(long));
  16291.                   l1 := 1234;
  16292.                   set_static_data(dataname, l1);
  16293.  
  16294.                   // Do some other things here, or even exit back
  16295.                   // to Maximus and restart the MEX program.
  16296.  
  16297.                   get_static_data(dataname, l2);
  16298.                   print("l2 = ", l2, '\n');
  16299.                   return 0;
  16300.                 }
  16301.  
  16302.  
  16303.              get_static_string
  16304.  
  16305.  
  16306.  
  16307.  
  16308.  Prototype   int get_static_string(string: key, ref string: data);
  16309.  
  16310.  Arguments   key   The key for the static string to be retrieved. This
  16311.              must be the same as the key parameter passed to cre-
  16312.              ate_static_string.
  16313.  
  16314.              data  A reference to the string to be updated with a copy of
  16315.              the static string.
  16316.  
  16317.  Return Val. 0 if the string was retrieved successfully;
  16318.              -1 if the key name was not found.
  16319.  
  16320.  Description The get_static_string function is used to retrieve strings
  16321.              that were previously stored by the set_static_string func-
  16322.              tion. If key is a valid static string key that was created by
  16323.              create_static_string, this function will retrieve the infor-
  16324.              mation in the static string and copy it into the local string
  16325.              referenced by data.
  16326.  
  16327.  Example     The following code creates a static string, writes a value to
  16328.              it, and then retrieves it again (without error checking):
  16329.  
  16330.                 #include <max.mh>
  16331.  
  16332.                 int main()
  16333.                 {
  16334.                   string: s1, s2;
  16335.                   string: stringname;
  16336.  
  16337.                   stringname := "test:mystring";
  16338.                   create_static_string(stringname);
  16339.                   s1 := "foo";
  16340.                   set_static_string(stringname, s1);
  16341.  
  16342.                   // Do some other things here, or even exit back
  16343.  
  16344.  
  16345.  
  16346.              15. MEX Library Reference                                 297
  16347.  
  16348.                   // to Maximus and restart.
  16349.  
  16350.                   get_static_string(stringname, s2);
  16351.                   print("s2 = '", s2, "'\n");
  16352.                   return 0;
  16353.                 }
  16354.  
  16355.  
  16356.  
  16357.              getch
  16358.  
  16359.  
  16360.  
  16361.  
  16362.  Prototype   char getch();
  16363.  
  16364.  Arguments   None
  16365.  
  16366.  Return Val. The character entered by the user.
  16367.  
  16368.  Description This function performs raw character input. It simply returns
  16369.              the character typed by the user. If no character is avail-
  16370.              able, Maximus will wait until the user presses a key.
  16371.  
  16372.              All of the normal Maximus input routines are used, so if the
  16373.              system operator enables local keyboard input, characters en-
  16374.              tered at the local console will also be retrieved by this
  16375.              function.
  16376.  
  16377.              Note that this function does not perform any input process-
  16378.              ing. Regardless of the user's hotkey setting, IBM characters
  16379.              setting, or other flags, Maximus will simply return the char-
  16380.              acter received over the modem. This includes scan codes and
  16381.              raw key codes from terminal programs running in "doorway
  16382.              mode" (and from the local console).
  16383.  
  16384.              Except in special cases where raw keyboard input is required,
  16385.              the input_ch function should be used instead of this func-
  16386.              tion. input_ch provides access to formatted data input, in-
  16387.              cluding command stacking for non-hotkey users, prompts, and
  16388.              more.
  16389.  
  16390.  
  16391.  
  16392.              hstr
  16393.  
  16394.  
  16395.  
  16396.  
  16397.  Prototype   string hstr(ref string: heapname, int: index);
  16398.  
  16399.  Arguments   heapname  Name of the heap from which the string is to be
  16400.              fetched.
  16401.  
  16402.  
  16403.  
  16404.              15. MEX Library Reference                                 298
  16405.  
  16406.              index Index number (within the heap) of the string to be
  16407.              fetched.
  16408.  
  16409.  Return Val. The string that matches the requested heap name and index, or
  16410.              the null string ("") if the heap/index pair could not be
  16411.              found.
  16412.  
  16413.  Description The hstr function is used to retrieve strings from MEX-
  16414.              specific language files. The heapname and index parameters
  16415.              combine to form a key that refers to a unique string in one
  16416.              of the user-defined language heaps in english.mad.
  16417.  
  16418.              This function is only used to retrieve MEX-specific strings
  16419.              from english.mad. These strings are always contained in heaps
  16420.              that start with an "=" character, rather than the ":" charac-
  16421.              ter that is used to begin the standard system language heaps.
  16422.  
  16423.              Calls to hstr are normally generated automatically by MAID
  16424.              when it creates the english.mh include file for MEX programs.
  16425.              When MAID parses a language file, it gathers information
  16426.              about all of the user-defined heaps. It then translates the
  16427.              name in front of each string into a MEX #define directive,
  16428.              which expands into a call to the hstr function using the cor-
  16429.              rect heapname and index parameters.
  16430.  
  16431.  
  16432.  
  16433.              input_ch
  16434.  
  16435.  
  16436.  
  16437.  
  16438.  Prototype   int input_ch(int: type, string: options);
  16439.  
  16440.  Arguments   type  This parameter specifies a number of options that con-
  16441.              trol the character input routine. Zero or more of the CIN-
  16442.              PUT_* constants can be specified, combined using the bitwise
  16443.              or operator. For a detailed list of CINPUT_ constants, see
  16444.              the description below.
  16445.  
  16446.              options   This string specifies an optional list of parame-
  16447.              ters. The contents of this string vary based on the settings
  16448.              used for type, as described below.
  16449.  
  16450.  Return Val. This function returns the character that is entered by the
  16451.              user.
  16452.  
  16453.  Description The input_ch function performs formatted character input. It
  16454.              calls the standard Maximus character input routines to get a
  16455.              key from the user. Among other things, this means that:
  16456.  
  16457.                 Hotkey mode is properly handled. If the user has hotkeys
  16458.                 enabled, the function will return as soon as a key is
  16459.  
  16460.  
  16461.  
  16462.              15. MEX Library Reference                                 299
  16463.  
  16464.                 pressed. Otherwise, Maximus will accept a line of input and
  16465.                 only return the first character.
  16466.  
  16467.                 Standard Maximus input functionality can also be enabled,
  16468.                 such as prompt display and <ctrl-c> handling.
  16469.  
  16470.                 Command stacking is supported.
  16471.  
  16472.              The type field controls how the input function operates. The
  16473.              field can be a combination of one or more of the values shown
  16474.              in Table 15.36. Multiple values can be combined using the
  16475.              bitwise or operator.
  16476.  
  16477.              Table 15.36 Character Input Types
  16478.  
  16479.               Type                 Description
  16480.  
  16481.               CINPUT_DISPLAY       The character entered by the user
  16482.                                    should always be displayed, even if
  16483.                                    hotkey mode is enabled. This option
  16484.                                    is implied for the input_list func-
  16485.                                    tion.
  16486.               CINPUT_ACCEPTABLE    Restrict the characters input by the
  16487.                                    user to the list of characters speci-
  16488.                                    fied in the options string. For exam-
  16489.                                    ple, if the CINPUT_ACCEPTABLE flag is
  16490.                                    specified, and if options contains
  16491.                                    "abeq", the user will only be able to
  16492.                                    enter an "A," "B," "E" or "Q" at the
  16493.                                    prompt.
  16494.               CINPUT_PROMPT        Display the prompt contained in op-
  16495.                                    tions before asking for input.
  16496.               CINPUT_SCAN          Accept scan codes. This option in-
  16497.                                    structs Maximus to return scan codes
  16498.                                    produced by function keys, cursor
  16499.                                    keys, and other special characters.
  16500.                                    (These scan codes can be created by
  16501.                                    pressing the appropriate function and
  16502.                                    cursor keys on the local SysOp key-
  16503.                                    board, and they can also be created
  16504.                                    by remote users who use terminal pro-
  16505.                                    grams in "DoorWay mode.")
  16506.                                    Although standard ASCII characters
  16507.                                    (such as letters, numbers, and punc-
  16508.                                    tuation) are still returned as a sin-
  16509.                                    gle character, when a function key or
  16510.                                    other non-ASCII character is pressed,
  16511.                                    input_key will return 0. In the fol-
  16512.                                    lowing call to input_key, the scan
  16513.                                    code of the key will be returned.
  16514.               CINPUT_NOXLT         Do not translate special characters,
  16515.                                    such as carriage returns and
  16516.                                    newlines, into their ASCII equiva-
  16517.  
  16518.  
  16519.  
  16520.              15. MEX Library Reference                                 300
  16521.  
  16522.                                    lents. (For example, unless this op-
  16523.                                    tion is used, <enter> will be re-
  16524.                                    turned as "|.") This option is im-
  16525.                                    plied for the input_list function.
  16526.               CINPUT_NOCTRLC       Do not allow the user to press <ctrl-
  16527.                                    c> to abort the current entry and re-
  16528.                                    display the prompt.
  16529.               CINPUT_P_CTRLC       The prompt specified in options will
  16530.                                    not be initially displayed; the
  16531.                                    prompt is only displayed if the user
  16532.                                    presses <ctrl-c>.
  16533.               CINPUT_NOLF          Do not display a linefeed after the
  16534.                                    user's input character selection is
  16535.                                    displayed.
  16536.               CINPUT_FULLPROMPT    Do not add a bracketed list of ac-
  16537.                                    ceptable characters to the prompt
  16538.                                    string. This option is only valid
  16539.                                    when used as parameter for the in-
  16540.                                    put_list function.
  16541.               CINPUT_ALLANSWERS    Allow the user to exit by pressing
  16542.                                    only <enter>, even if CIN-
  16543.                                    PUT_ACCEPTABLE is also specified.
  16544.               CINPUT_DUMP          Flush the output buffer when a char-
  16545.                                    acter is received. This option is
  16546.                                    mostly useful in hotkey mode. This
  16547.                                    option is also implied for the in-
  16548.                                    put_list function.
  16549.               CINPUT_NOUPPER       Do not convert received characters to
  16550.                                    uppercase.
  16551.               CINPUT_AUTOP         Display the prompt, even if the user
  16552.                                    has hotkeys enabled.
  16553.               CINPUT_ANY           Any response to this function is
  16554.                                    valid, even if not contained in list.
  16555.                                    This option is only valid when used
  16556.                                    as a parameter for the input_list
  16557.                                    function.
  16558.  
  16559.  
  16560.  
  16561.              input_list
  16562.  
  16563.  
  16564.  
  16565.  
  16566.  Prototype   int input_list(string: list, int: type, string: help_file,
  16567.              string: invalid,
  16568.                   string: prompt);
  16569.  
  16570.  Arguments   list  This string contains a list of acceptable input charac-
  16571.              ters. To allow a character that is not present in list, in-
  16572.              clude the CINPUT_ANY option in the type parameter. The first
  16573.              uppercase character in the string will be chosen as the de-
  16574.  
  16575.  
  16576.  
  16577.              15. MEX Library Reference                                 301
  16578.  
  16579.              fault option and will be selected if the user presses <enter>
  16580.              at the prompt.
  16581.  
  16582.              type  This parameter specifies a number of options that con-
  16583.              trol the character input routine. Zero or more of the CIN-
  16584.              PUT_* constants can be combined using the bitwise or opera-
  16585.              tor. For a detailed list of acceptable CINPUT_ constants, see
  16586.              the description of the input_ch function, above.
  16587.  
  16588.              help_file If not a blank string, this specifies the name of
  16589.              the help file to be displayed when a question mark ("?") is
  16590.              entered by the user. If this is not a blank string, Maximus
  16591.              will also add a "=help" to the end of prompt.
  16592.  
  16593.              invalid   This string is displayed to the user when an inva-
  16594.              lid character is entered.
  16595.  
  16596.              promptThis string contains a prompt to be displayed to the
  16597.              user. Unless the CINPUT_FULLPROMPT option is included in the
  16598.              type parameter, a bracketed list of acceptable option letters
  16599.              is automatically added to the end of this string.
  16600.  
  16601.  Return Val. This function returns the option character entered by the
  16602.              user.
  16603.  
  16604.  Description The input_list function prompts the user to enter a character
  16605.              from a predefined set of options. A typical prompt generated
  16606.              by input_list looks something like this:
  16607.  
  16608.                 Do you prefer lettuce, cabbage or broccoli [L,c,b]?
  16609.  
  16610.              The first part of the prompt, "Do you prefer lettuce, cabbage
  16611.              or broccoli," is provided in the prompt parameter.
  16612.  
  16613.              The second part of the prompt, "[L,c,b]?" is automatically
  16614.              added by input_list. By specifying the valid input characters
  16615.              in the list string as "Lcb," the input_list function will
  16616.              automatically format the "[L,c,b]" text and add the final
  16617.              question mark. Since the "L" is uppercase, it will be chosen
  16618.              as the default option if the user presses <enter>.
  16619.  
  16620.  Example     The following code implements the prompt described above:
  16621.  
  16622.                 #include <max.mh>
  16623.  
  16624.                 int main()
  16625.                 {
  16626.                   int: ch;
  16627.  
  16628.                   ch := input_list("Lcb",
  16629.                                    0,
  16630.                                    "",
  16631.                                    "That is an invalid type of "
  16632.  
  16633.  
  16634.  
  16635.              15. MEX Library Reference                                 302
  16636.  
  16637.                                      "produce. ",
  16638.                                    "Do you prefer lettuce, "
  16639.                                   "cabbage or broccoli");
  16640.  
  16641.                   return 0;
  16642.                 }
  16643.  
  16644.  
  16645.  
  16646.              input_str
  16647.  
  16648.  
  16649.  
  16650.  
  16651.  Prototype   int input_str(ref string: s, int: type, char: ch, int: max,
  16652.              string: prompt);
  16653.  
  16654.  Arguments   s     On return, this variable will be updated to contain the
  16655.              text entered by the user.
  16656.  
  16657.              type  This parameter contains one or more INPUT_* options,
  16658.              combined using the bitwise or operator, which control how
  16659.              Maximus reads input from the user. These options are de-
  16660.              scribed in more detail in the function description, below.
  16661.  
  16662.              ch    This special-purpose parameter is only used when a cer-
  16663.              tain subset of the INPUT_* options are specified in the type
  16664.              field, as indicated in the table below. Otherwise, this pa-
  16665.              rameter should be 0.
  16666.  
  16667.              max   The maximum length of the string to be returned in s.
  16668.  
  16669.              promptThe prompt to be displayed to the user before request-
  16670.              ing input.
  16671.  
  16672.  Return Val. This function returns the length of the string placed in s.
  16673.  
  16674.  Description The input_str function displays a prompt and waits for the
  16675.              user to enter a word or a string. This string is returned in
  16676.              the s parameter where it can be later examined by the MEX
  16677.              program.
  16678.  
  16679.              The type parameter specifies a number of options that control
  16680.              how the input function reacts to user input. It also controls
  16681.              whether or not command accepts a word or a string, and
  16682.              whether or not command stacking is allowed.
  16683.  
  16684.              The type parameter must contain exactly one of the following
  16685.              mutually-exclusive options: INPUT_LB_LINE, INPUT_NLB_LINE,
  16686.              and INPUT_WORD. All of the other parameters in Table 15.37
  16687.              are optional and can be specified in any combination.
  16688.  
  16689.  
  16690.  
  16691.              15. MEX Library Reference                                 303
  16692.  
  16693.              Table 15.37 Line Input Types
  16694.  
  16695.               Type                 Description
  16696.  
  16697.               INPUT_LB_LINE        Read an entire line of input from the
  16698.                                    user. Command stacking is enabled, so
  16699.                                    if any unused input is in the stack-
  16700.                                    ing buffer (accessible as the global
  16701.                                    variable input), it will be returned
  16702.                                    without displaying the prompt or ask-
  16703.                                    ing the user for more input.
  16704.               INPUT_NLB_LINE       Read an entire line of input from the
  16705.                                    user. Command stacking is disabled,
  16706.                                    so the contents of the line buffer
  16707.                                    (accessible as the global variable
  16708.                                    input) are ignored. The prompt is al-
  16709.                                    ways displayed and the user is always
  16710.                                    asked for input.
  16711.               INPUT_WORD           Read a single word from the user.
  16712.                                    Command stacking is always enabled.
  16713.                                    If there is unused input in the
  16714.                                    stacking buffer (accessible as the
  16715.                                    global variable input), the first
  16716.                                    word therein will be returned without
  16717.                                    displaying the prompt or asking the
  16718.                                    user for more input. In this context,
  16719.                                    a "word" is delimited by one or more
  16720.                                    spaces. If the stacking buffer is
  16721.                                    empty, the prompt will be displayed
  16722.                                    and Maximus will wait for the user to
  16723.                                    enter an entire string. The first
  16724.                                    word of this string (delimited by
  16725.                                    spaces) will be returned, and the
  16726.                                    rest of the string will remain in the
  16727.                                    line buffer.
  16728.  
  16729.               INPUT_ECHO           The character specified in ch is ech-
  16730.                                    oed back instead of the actual char-
  16731.                                    acter typed by the user. This is use-
  16732.                                    ful for designing prompts for pass-
  16733.                                    words or other sensitive information.
  16734.                                    This option and INPUT_NOECHO are mu-
  16735.                                    tually exclusive. (If neither option
  16736.                                    is specified, Maximus will echo the
  16737.                                    characters normally.)
  16738.               INPUT_NOECHO         Do not echo any characters back to
  16739.                                    the remote. This option and IN-
  16740.                                    PUT_ECHO are mutually exclusive.
  16741.  
  16742.               INPUT_ALREADYCH      Pretend that the user has already en-
  16743.                                    tered the character given in ch. This
  16744.                                    is useful if an input sequence is
  16745.                                    chained off a hotkeyed menu option,
  16746.  
  16747.  
  16748.  
  16749.              15. MEX Library Reference                                 304
  16750.  
  16751.                                    or some other form of input that re-
  16752.                                    trieves the first input character
  16753.                                    manually.
  16754.               INPUT_SCAN           Allow scan codes to be placed in the
  16755.                                    returned string. See the description
  16756.                                    of CINPUT_SCAN in the input_ch func-
  16757.                                    tion for more information on scan
  16758.                                    code formats.
  16759.               INPUT_NOCTRLC        Do not allow the user to press <ctrl-
  16760.                                    c> to abort the current input and re-
  16761.                                    display the prompt.
  16762.               INPUT_NOLF           Do not send a linefeed after the user
  16763.                                    has finished entering the string.
  16764.               INPUT_WORDWRAP       Allow word-wrapping.
  16765.               INPUT_NOCLEOL        Never issue clear-to-end-of-line
  16766.                                    (CLEOL) codes.
  16767.               INPUT_DEFAULT        On input, pretend that the contents
  16768.                                    of s were already entered by the
  16769.                                    user. This option is useful if the
  16770.                                    first part of an input string is to
  16771.                                    be automatically generated. (However,
  16772.                                    the user can use the backspace key to
  16773.                                    modify this input.) On output, s will
  16774.                                    be updated with the full string by
  16775.                                    the user.
  16776.  
  16777.  
  16778.  
  16779.              iskeyboard
  16780.  
  16781.  
  16782.  
  16783.  
  16784.  Prototype   int iskeyboard();
  16785.  
  16786.  Arguments   None
  16787.  
  16788.  Return Val. TRUE if the local keyboard mode is active; FALSE otherwise.
  16789.  
  16790.  Description This function is used to determine whether or not the local
  16791.              keyboard mode (toggled by the "A" character on the SysOp con-
  16792.              sole) is active.
  16793.  
  16794.              Note that local sessions are always considered to be running
  16795.              in local keyboard mode.
  16796.  
  16797.  
  16798.  
  16799.              15. MEX Library Reference                                 305
  16800.  
  16801.  
  16802.              issnoop
  16803.  
  16804.  
  16805.  
  16806.  
  16807.  Prototype   int issnoop();
  16808.  
  16809.  Arguments   None
  16810.  
  16811.  Return Val. TRUE if snoop mode is active; FALSE otherwise.
  16812.  
  16813.  Description This function determines whether or not Snoop mode is active.
  16814.              If snoop mode is enabled, the output sent to the remote user
  16815.              will also be echoed on the local screen. Snoop mode is en-
  16816.              abled on the local console by pressing the "N" key.
  16817.  
  16818.  
  16819.  
  16820.              itostr
  16821.  
  16822.  
  16823.  
  16824.  
  16825.  Prototype   string itostr(int: i);
  16826.  
  16827.  Arguments   i     The integer to be converted.
  16828.  
  16829.  Return Val. This function returns the string representation of the inte-
  16830.              ger.
  16831.  
  16832.  Description The itostr function is used to convert an integer to a
  16833.              string. The converted string contains the ASCII representa-
  16834.              tion of the integer, from -32768 to 32767. See the uitostr
  16835.              function for converting unsigned integers.
  16836.  
  16837.              This function is useful when strings must be mixed with the
  16838.              results of integral computations.
  16839.  
  16840.  Example     This code concatenates a string and a converted integer:
  16841.  
  16842.                 #include <max.mh>
  16843.  
  16844.                 int main()
  16845.                 {
  16846.                   int: i1;
  16847.                   string: s;
  16848.  
  16849.                   i1 := 1000;
  16850.                   s := "MEX is used by " + itostr(i1) + "s of "
  16851.                        + "programmers";
  16852.  
  16853.                   print(s);
  16854.  
  16855.  
  16856.  
  16857.              15. MEX Library Reference                                 306
  16858.  
  16859.                   return 0;
  16860.                 }
  16861.  
  16862.  
  16863.  
  16864.              kbhit
  16865.  
  16866.  
  16867.  
  16868.  
  16869.  Prototype   int kbhit();
  16870.  
  16871.  Arguments   None
  16872.  
  16873.  Return Val. TRUE if a character is waiting; FALSE otherwise.
  16874.  
  16875.  Description The kbhit function is used to determine if a character has
  16876.              been pressed by the remote user (or on the local console, if
  16877.              local keyboard mode is enabled).
  16878.  
  16879.              If a character has been pressed, any of the input_str, in-
  16880.              put_list, input_ch or getch functions can be used to retrieve
  16881.              the character.
  16882.  
  16883.  
  16884.  
  16885.              keyboard
  16886.  
  16887.  
  16888.  
  16889.  
  16890.  Prototype   int keyboard(int: state);
  16891.  
  16892.  Arguments   state The new state for keyboard mode. If this parameter is
  16893.              1, local keyboard mode is enabled. If this parameter is 0,
  16894.              local keyboard mode is disabled.
  16895.  
  16896.  Return Val. The prior state of the local keyboard setting.
  16897.  
  16898.  Description The keyboard function is used to set or reset the local key-
  16899.              board mode. This function is primarily useful when a MEX pro-
  16900.              gram wishes to explicitly allow the SysOp to enter charac-
  16901.              ters, even if local keyboard mode was originally off.
  16902.  
  16903.              The return value of this function can be used at a later
  16904.              point in time to reset local keyboard mode to its original
  16905.              state.
  16906.  
  16907.  
  16908.  
  16909.              15. MEX Library Reference                                 307
  16910.  
  16911.  
  16912.              language_num_to_name
  16913.  
  16914.  
  16915.  
  16916.  
  16917.  Prototype   string language_num_to_name(int: lang);
  16918.  
  16919.  Arguments   lang  An integer index for a language defined in the language
  16920.              control file.
  16921.  
  16922.  Return Val. A string containing the name of the language, or the null
  16923.              string ("") if the language index is invalid.
  16924.  
  16925.  Description This function is used to translate the usr.lang field in the
  16926.              user structure to obtain a human-readable string.
  16927.  
  16928.  
  16929.  
  16930.              localkey
  16931.  
  16932.  
  16933.  
  16934.  
  16935.  Prototype   int localkey();
  16936.  
  16937.  Arguments   None
  16938.  
  16939.  Return Val. TRUE if the last getch or kbhit returned a character that was
  16940.              entered on the SysOp console or by a local session; FALSE if
  16941.              the character was entered by a remote user.
  16942.  
  16943.  Description The localkey function is used to determine the source of the
  16944.              most recent keystroke. This function can be useful if the
  16945.              processing of a character depends on whether the key was en-
  16946.              tered by a remote user or by the SysOp (or a caller logged on
  16947.              at the console).
  16948.  
  16949.  
  16950.  
  16951.              log
  16952.  
  16953.  
  16954.  
  16955.  
  16956.  Prototype   void log(string: text);
  16957.  
  16958.  Arguments   text  Line to be placed in the system log. The first charac-
  16959.              ter of the string should indicate the priority of the log
  16960.              message, such as "!" or "#." The second and following charac-
  16961.              ters of the string represent the line to be logged.
  16962.  
  16963.  Return Val. None
  16964.  
  16965.  
  16966.  
  16967.              15. MEX Library Reference                                 308
  16968.  
  16969.  Description This function adds the specified line to the Maximus system
  16970.              log file.
  16971.  
  16972.  Example     Given the following code:
  16973.  
  16974.                 log("!Could not find user record!");
  16975.  
  16976.              The code above would create a log entry similar to the one
  16977.              shown below:
  16978.  
  16979.                 ! 12 Jul 95 15:33:02 MAX  Could not find user record!
  16980.  
  16981.  
  16982.  
  16983.  
  16984.              long_to_stamp
  16985.  
  16986.  
  16987.  
  16988.  
  16989.  Prototype   void long_to_stamp(long: time, ref struct _stamp: st);
  16990.  
  16991.  Arguments   time  A long integer containing the time value to be con-
  16992.              verted. The value contained in this parameter represents the
  16993.              number of seconds elapsed since January 1st, 1970 (UTC).
  16994.  
  16995.              st    A reference to a _stamp structure. Upon return, this
  16996.              structure will be updated with values representing the time
  16997.              given by time.
  16998.  
  16999.  Return Val. None
  17000.  
  17001.  Description This function is used to convert the result of the time func-
  17002.              tion into a human-readable result. The values placed in the
  17003.              st structure correspond to the current date and time, ex-
  17004.              pressed in terms of the current year, day, month, hour, min-
  17005.              ute and second.
  17006.  
  17007.  
  17008.  
  17009.              lstr
  17010.  
  17011.  
  17012.  
  17013.  
  17014.  Prototype   string lstr(int: index);
  17015.  
  17016.  Arguments   index An integer representing one of the strings in the eng-
  17017.              lish.mad language file.
  17018.  
  17019.  Return Val. The string specified by the index parameter, or the null
  17020.              string ("") if an invalid index number was specified.
  17021.  
  17022.  
  17023.  
  17024.              15. MEX Library Reference                                 309
  17025.  
  17026.  Description The lstr function is used to retrieve a string from the stan-
  17027.              dard strings in the system language file. (System language
  17028.              heaps are always declared in english.mad using the ":" char-
  17029.              acter. To contrast, user-specific heaps ---which are re-
  17030.              trieved using the hstr function ---are always declared using
  17031.              the "=" character.)
  17032.  
  17033.              To find the index for a particular string in the language
  17034.              file, add a "@MEX" prefix before the definition of the string
  17035.              in english.mad. When MAID writes out the english.lh file, it
  17036.              will generate a #define which automatically calls the lstr
  17037.              function using the appropriate string number.
  17038.  
  17039.  
  17040.  
  17041.              ltostr
  17042.  
  17043.  
  17044.  
  17045.  
  17046.  Prototype   string ltostr(long: l);
  17047.  
  17048.  Arguments   l     The long integer to be converted.
  17049.  
  17050.  Return Val. This function returns the string representation of the long
  17051.              integer.
  17052.  
  17053.  Description The ltostr function is used to convert a long integer to a
  17054.              string. The converted string contains the ASCII representa-
  17055.              tion of the long integer, from -2147483648 to 2147483647. See
  17056.              the ultostr function for converting unsigned longs.
  17057.  
  17058.              This function is useful when strings must be mixed with the
  17059.              results of integral computations.
  17060.  
  17061.  Example     See the description for the itostr function for a related ex-
  17062.              ample.
  17063.  
  17064.  
  17065.  
  17066.              mdm_command
  17067.  
  17068.  
  17069.  
  17070.  
  17071.  Prototype   int mdm_command(string: cmdstring);
  17072.  
  17073.  Arguments   cmdstring The command to be sent to the modem. This string
  17074.              uses all of the same translation characters as in the modem
  17075.              initialization and busy strings from the Maximus control
  17076.              files, such as "|" for <enter> and "~" for a one-second
  17077.              pause. Please see the Busy keyword in section 18.2.2 for more
  17078.              information.
  17079.  
  17080.  
  17081.  
  17082.              15. MEX Library Reference                                 310
  17083.  
  17084.  Return Val. TRUE if the string was transmitted successfully; FALSE other-
  17085.              wise.
  17086.  
  17087.  Description The mdm_command function transmits a command string to the
  17088.              modem. This function is normally only used when talking di-
  17089.              rectly to the modem, rather than when a user is on-line.
  17090.  
  17091.  
  17092.  
  17093.              mdm_flow
  17094.  
  17095.  
  17096.  
  17097.  
  17098.  Prototype   void mdm_flow(int: state);
  17099.  
  17100.  Arguments   state A flag describing the desired state of XON/XOFF flow
  17101.              control. If this flag is set to 1, XON/XOFF flow control will
  17102.              be enabled if the SysOp has enabled Mask Handshaking XON. If
  17103.              this flag is set to 0, XON/XOFF flow control will always be
  17104.              disabled.
  17105.  
  17106.  Return Val. None
  17107.  
  17108.  Description This function enables or disables software handshaking. Soft-
  17109.              ware handshaking normally needs to be disabled before trying
  17110.              to communicate directly with the modem.
  17111.  
  17112.  
  17113.  
  17114.              menu_cmd
  17115.  
  17116.  
  17117.  
  17118.  
  17119.  Prototype   void menu_cmd(int: cmdnum, string: args);
  17120.  
  17121.  Arguments   cmdnumThe MNU_* constant describing the menu option to exe-
  17122.              cute. The max_menu.mh header file must be included (with the
  17123.              #include directive) to define the MNU_* constants.
  17124.  
  17125.              args  Arguments for the menu command. These arguments are
  17126.              specified in string format. Most menu commands do not require
  17127.              arguments; the only functions which require arguments are
  17128.              those which have an argument specified in the second column
  17129.              in the menus control file. For all other menu option types,
  17130.              this string should be the null string ("").
  17131.  
  17132.  Return Val. None
  17133.  
  17134.  Description The menu_cmd function executes an internal Maximus menu com-
  17135.              mand. Sample actions include entering a message, performing a
  17136.  
  17137.  
  17138.  
  17139.              15. MEX Library Reference                                 311
  17140.  
  17141.              new files search, and invoking most of the other commands in
  17142.              menus.ctl.
  17143.  
  17144.              The main restrictions for menu_cmd are:
  17145.  
  17146.              *  The Display_File menu command cannot be invoked. (Instead,
  17147.                 see the display_file MEX function.)
  17148.  
  17149.              *  The Edit_* menu commands cannot be invoked unless the user
  17150.                 is already running either the MaxEd or the BORED editor.
  17151.  
  17152.              *  The MEX, Xtern_Erlvl, Link_Menu, Return and Display_Menu
  17153.                 menu commands cannot be invoked.
  17154.  
  17155.  
  17156.  
  17157.              msg_area
  17158.  
  17159.  
  17160.  
  17161.  
  17162.  Prototype   void msg_area();
  17163.  
  17164.  Arguments   None
  17165.  
  17166.  Return Val. None
  17167.  
  17168.  Description This function displays the message area menu. Calling
  17169.              msg_area is equivalent to calling menu_cmd(MNU_MSG_AREA, ""),
  17170.              although calling msg_area is slightly faster.
  17171.  
  17172.  
  17173.  
  17174.              msgareafindclose
  17175.  
  17176.  
  17177.  
  17178.  
  17179.  Prototype   void msgareafindclose();
  17180.  
  17181.  Arguments   None
  17182.  
  17183.  Return Val. None
  17184.  
  17185.  Description The msgareafindclose function terminates an existing msgare-
  17186.              afindfirst search. This function should be called whenever
  17187.              the program has finished using the message area data file.
  17188.  
  17189.  
  17190.  
  17191.              15. MEX Library Reference                                 312
  17192.  
  17193.  
  17194.              msgareafindfirst
  17195.  
  17196.  
  17197.  
  17198.  
  17199.  Prototype   int msgareafindfirst(ref struct _marea: ma, string: name,
  17200.              int: flags);
  17201.  
  17202.  Arguments   ma    A reference to a message area information structure. If
  17203.              this function finds a message area matching the name and
  17204.              flags parameters, information about that message area will be
  17205.              placed in this structure.
  17206.  
  17207.              name  Name of a specific message area to find. If name is the
  17208.              null string (""), this function will find the first available
  17209.              message area.
  17210.  
  17211.              flags A flag indicating whether or not MsgDivisionBegin and
  17212.              MsgDivisionEnd records are to be returned. If this flag is
  17213.              equal to AFFO_DIV, division records will be returned. Other-
  17214.              wise, if this flag is equal to AFFO_NODIV, division records
  17215.              will be skipped.
  17216.  
  17217.  Return Val. TRUE if an area was found; FALSE otherwise.
  17218.  
  17219.  Description The msgareafindfirst function searches for a specific message
  17220.              area, as specified by the name parameter. It also finds divi-
  17221.              sion records within the area file if the AFFO_DIV flag is
  17222.              specified.
  17223.  
  17224.              Only areas which can be accessed by the user will be returned
  17225.              by this function. This function will also skip message areas
  17226.              that have the "Hidden" style.
  17227.  
  17228.  Example     The following code will display a list of all message areas:
  17229.  
  17230.                 #include <max.mh>
  17231.  
  17232.                 int main()
  17233.                 {
  17234.                   struct _marea: ma;
  17235.  
  17236.                   if (msgareafindfirst (ma, "", AFFO_NODIV))
  17237.                   {
  17238.                        do
  17239.                        {
  17240.                             print("Area: ", ma.name, '\n');
  17241.                        }
  17242.                        while (msgareafindnext (ma));
  17243.  
  17244.                        msgareafindclose();
  17245.                   }
  17246.  
  17247.  
  17248.  
  17249.              15. MEX Library Reference                                 313
  17250.  
  17251.  
  17252.                   return 0;
  17253.                 }
  17254.  
  17255.  
  17256.  
  17257.              msgareafindnext
  17258.  
  17259.  
  17260.  
  17261.  
  17262.  Prototype   int msgareafindnext(ref struct _marea: ma);
  17263.  
  17264.  Arguments   ma    A reference to the message area structure to be updated
  17265.              with message area information. This structure must have been
  17266.              originally filled in by a msgareafindfirst, msgareafindnext,
  17267.              or msgareafindprev call.
  17268.  
  17269.  Return Val. TRUE if another message area was found; FALSE if no message
  17270.              area could be found.
  17271.  
  17272.  Description The msgareafindnext function finds the next message area that
  17273.              is accessible to the user. The search is carried out from the
  17274.              position where the last msgareafindnext, msgareafindprev, or
  17275.              msgareafindfirst call terminated. Consequently, if the last
  17276.              msgareafind* call returned information for area "X", this
  17277.              function would return information for the next user-
  17278.              accessible area following area "X".
  17279.  
  17280.  
  17281.  
  17282.              msgareafindprev
  17283.  
  17284.  
  17285.  
  17286.  
  17287.  Prototype   int msgareafindprev(ref struct _marea: ma);
  17288.  
  17289.  Arguments   ma    A reference to the message area structure to be updated
  17290.              with message area information. This structure must have been
  17291.              originally filled in by a msgareafindfirst, msgareafindnext,
  17292.              or msgareafindprev call.
  17293.  
  17294.  Return Val. TRUE if another message area was found; FALSE if no message
  17295.              area could be found.
  17296.  
  17297.  Description The msgareafindnext function finds the previous message area
  17298.              that is accessible to the user. The search is carried out
  17299.              from the position the last msgareafindnext, msgareafindprev,
  17300.              or msgareafindfirst call terminated. Consequently, if the
  17301.              last msgareafind* call returned information for area "X",
  17302.              this function would return information for the first user-
  17303.              accessible area that precedes area "X".
  17304.  
  17305.  
  17306.  
  17307.              15. MEX Library Reference                                 314
  17308.  
  17309.  
  17310.              msgareaselect
  17311.  
  17312.  
  17313.  
  17314.  
  17315.  Prototype   int msgareaselect(string: name);
  17316.  
  17317.  Arguments   name  Name of the message area to be selected as the user's
  17318.              current message area
  17319.  
  17320.  Return Val. TRUE if the area was successfully selected; FALSE otherwise.
  17321.  
  17322.  Description The msgareaselect function is used to change the user's cur-
  17323.              rent message area. Upon return, this function also updates
  17324.              the global marea and msg structures with information about
  17325.              the new message area.
  17326.  
  17327.  
  17328.  
  17329.              open
  17330.  
  17331.  
  17332.  
  17333.  
  17334.  Prototype   int open(string: name, int: mode);
  17335.  
  17336.  Arguments   name  The name of the file to be opened.
  17337.  
  17338.                    WARNING!
  17339.  
  17340.                    All backslashes must be escaped in MEX programs. For
  17341.                    example, to specify a file called \max\misc\foo.bbs,
  17342.                    the parameter must contain "\\max\\misc\\foo.bbs".
  17343.  
  17344.              mode  One or more IOPEN_* constants specifying the mode to be
  17345.              used when opening the file. The bitwise or operator can be
  17346.              used to combine multiple IOPEN_ constants. This parameter is
  17347.              described below in more detail.
  17348.  
  17349.  Return Val. -1 if an error occurs; otherwise, open returns an integer
  17350.              which identifies the opened file. This identifier must be
  17351.              stored and passed to the other MEX I/O functions when the
  17352.              file is to be accessed.
  17353.  
  17354.  Description The open function opens a file.  Depending on the value of
  17355.              mode, this function can be used to open an existing file or
  17356.              create a new one.
  17357.  
  17358.              The mode parameter indicates the file-opening mode. mode
  17359.              should contain exactly one of the constants from Table 15.38.
  17360.  
  17361.  
  17362.  
  17363.              15. MEX Library Reference                                 315
  17364.  
  17365.              Table 15.38 File Open Modes
  17366.  
  17367.               Mode           Description
  17368.  
  17369.               IOPEN_READ     Open the file for reading
  17370.               IOPEN_WRITE    Open the file for writing
  17371.  
  17372.  
  17373.  
  17374.              In addition, any of the modifiers from Table 15.39 can also
  17375.              be used if IOPEN_WRITE is specified:
  17376.  
  17377.              Table 15.39 File Open Modifiers
  17378.  
  17379.  
  17380.               Mode            Description
  17381.  
  17382.               IOPEN_APPEND    Append to the end of the file.
  17383.               IOPEN_CREATE    Create the file if it does not exist, or
  17384.                               truncate the file if it does.
  17385.               IOPEN_BINARY    Open the file in binary mode. This option
  17386.                               suppresses the translation of end-of-line
  17387.                               characters.
  17388.  
  17389.  
  17390.  
  17391.  Example     The following code creates a file called c:\test.fil and
  17392.              makes the file ready for writing:
  17393.  
  17394.                 int: fd;
  17395.  
  17396.                 fd := open("c:\\test.fil",
  17397.                            IOPEN_CREATE | IOPEN_WRITE);
  17398.  
  17399.  
  17400.              print
  17401.  
  17402.  
  17403.  
  17404.  
  17405.  Prototype   void print(...);
  17406.  
  17407.  Arguments   Any number of parameters (with any type) can be specified.
  17408.              See the function description for more information.
  17409.  
  17410.  Return Val. None
  17411.  
  17412.  Description print is used to display text to the user. print can display
  17413.              any type of information, including characters, integers,
  17414.              strings, or even user-defined structures or data types.
  17415.  
  17416.  
  17417.  
  17418.              15. MEX Library Reference                                 316
  17419.  
  17420.              Any number of parameters may be specified to print, and all
  17421.              will be displayed using formatting routines appropriate to
  17422.              the data type.
  17423.  
  17424.              The print function displays the information specified in its
  17425.              parameters, but it does not automatically place the cursor on
  17426.              the next line. To add this functionality, include a `\n' pa-
  17427.              rameter at the end of the function call.
  17428.  
  17429.              print handles the data types shown in Table 15.40 by default:
  17430.  
  17431.              Table 15.40 Print Data Types
  17432.  
  17433.               Type      Description
  17434.  
  17435.               char      Display a character in its natural format. For
  17436.                         example, the character `A' will be displayed
  17437.                         simply as "A." Control characters and high-bit
  17438.                         characters will also be displayed as-is, al-
  17439.                         though all print output will pass through the
  17440.                         standard Maximus output filter. This means that
  17441.                         high-bit characters may sometimes be replaced
  17442.                         with ASCII equivalents, and terminal control se-
  17443.                         quences may be stripped. (See section 13 for
  17444.                         more information.)
  17445.               int       Display an integer in decimal. The range for
  17446.                         signed integers is minus 32768 to 32767.
  17447.               long      Display a long integer in decimal. The range for
  17448.                         longs is minus 2147483648 to 2147483647.
  17449.               unsigned  Display an unsigned integer in decimal. The
  17450.               int       range for unsigned integers is 0 to 65535.
  17451.               unsigned  Display an unsigned long in decimal. The range
  17452.               long      for unsigned longs is 0 to 4294967296.
  17453.               string    Display a string. The string will be displayed
  17454.                         just as if each of the characters inside had
  17455.                         been displayed individually as a char, as above.
  17456.  
  17457.  
  17458.              print itself is just a meta-function ---there is no real
  17459.              function called "print" in the MEX run-time library. However,
  17460.              when the compiler encounters a print statement, it splits
  17461.              apart all of the arguments and calls a separate function for
  17462.              each.
  17463.  
  17464.              For an argument with a type of mytype, the MEX compiler will
  17465.              generate a call to a function of the form:
  17466.  
  17467.                 __printMYTYPE(data);
  17468.  
  17469.              where MYTYPE is the uppercase name of the type to be dis-
  17470.              played. The standard run-time library includes the following
  17471.              print handlers:
  17472.  
  17473.  
  17474.  
  17475.              15. MEX Library Reference                                 317
  17476.  
  17477.                 __printSTRING
  17478.                 __printLONG
  17479.                 __printINT
  17480.                 __printCHAR
  17481.                 __printUNSIGNED_LONG
  17482.                 __printUNSIGNED_INT
  17483.                 __printUNSIGNED_CHAR
  17484.  
  17485.              Support for user-defined data types can also be added to
  17486.              print by defining a new print function to handle the appro-
  17487.              priate argument type. For example, given a data type and an
  17488.              appropriate print handler function:
  17489.  
  17490.                 struct complex
  17491.                 {
  17492.                   int: real;
  17493.                   int: imaginary;
  17494.                 };
  17495.  
  17496.                 void __printSTRUCT_COMPLEX(ref struct complex: c)
  17497.                 {
  17498.                   print('(', c.real, ',', c.imaginary, ')');
  17499.                 }
  17500.  
  17501.              With these definitions, the print function can be used to
  17502.              print a structure of type complex by simply passing the
  17503.              structure as a parameter:
  17504.  
  17505.                 struct complex: c;
  17506.  
  17507.                 c.real := 5;
  17508.                 c.imaginary := 10;
  17509.  
  17510.                 print("The complex number is ", c, ".\n");
  17511.  
  17512.  
  17513.  
  17514.              privok
  17515.  
  17516.  
  17517.  
  17518.  
  17519.  Prototype   int privok(string: acs);
  17520.  
  17521.  Arguments   acs   The Access Control String (ACS) to be checked.
  17522.  
  17523.  Return Val. TRUE if the user's privilege level passes the privilege level
  17524.              check; FALSE otherwise.
  17525.  
  17526.  Description The privok function is used to check a user's privilege level
  17527.              against a given Access Control String. The ACS check per-
  17528.              formed by this function is the same as in all other areas of
  17529.  
  17530.  
  17531.  
  17532.              15. MEX Library Reference                                 318
  17533.  
  17534.              Maximus, so all of the standard ACS modifiers (">=", "!", and
  17535.              so on) can be specified in acs.
  17536.  
  17537.  
  17538.  
  17539.              prm_string
  17540.  
  17541.  
  17542.  
  17543.  
  17544.  Prototype   string prm_string(int: stringnum);
  17545.  
  17546.  Arguments   stringnum The string number to be retrieved from the Maximus
  17547.              .prm file. A string number of 0 specifies the first string.
  17548.  
  17549.  Return Val. The string that was retrieved, or the null string ("") if the
  17550.              string number is invalid.
  17551.  
  17552.  Description This function retrieves a string from the Maximus .prm file.
  17553.              The string number specifies an offset within the fixed-length
  17554.              string index table. The string numbers are version-specific
  17555.              and are subject to change without notice.
  17556.  
  17557.  
  17558.  
  17559.              protocol_num_to_name
  17560.  
  17561.  
  17562.  
  17563.  
  17564.  Prototype   string protocol_num_to_name(int: protocol);
  17565.  
  17566.  Arguments   protocol  An integer index for a protocol defined in proto-
  17567.              col.ctl.
  17568.  
  17569.  Return Val. A string containing the name of the protocol, or the null
  17570.              string ("") if the protocol index is invalid.
  17571.  
  17572.  Description This function is used to translate the usr.def_proto field in
  17573.              the user structure to obtain a human-readable string.
  17574.  
  17575.  
  17576.  
  17577.              read
  17578.  
  17579.  
  17580.  
  17581.  
  17582.  Prototype   int read(int: fd, ref string: s, int: len);
  17583.  
  17584.  Arguments   fd    A file descriptor, as returned by the open function.
  17585.  
  17586.  
  17587.  
  17588.              15. MEX Library Reference                                 319
  17589.  
  17590.              s     A reference to a string. Upon return, this string is
  17591.              filled in with the bytes read from the file.
  17592.  
  17593.              len   The maximum number of bytes to place into the string s.
  17594.  
  17595.  Return Val. If the return value is the same as len, the read was com-
  17596.              pletely successful.
  17597.  
  17598.              If the return value is less than len (but greater than zero),
  17599.              only a portion of the requested number of bytes could be
  17600.              read.
  17601.  
  17602.              If the return value is 0, end-of-file was encountered.
  17603.  
  17604.              If the return value is -1, an error occurred when trying to
  17605.              read from the file.
  17606.  
  17607.  Description The read function reads a block of bytes from the specified
  17608.              file handle. This function reads blocks of bytes at a time
  17609.              with no consideration for "lines" in the source file. To read
  17610.              a file a line at a time, see the readln function.
  17611.  
  17612.  
  17613.  
  17614.              readln
  17615.  
  17616.  
  17617.  
  17618.  
  17619.  Prototype   int readln(int: fd, ref string: s);
  17620.  
  17621.  Arguments   fd    A file descriptor, as returned by the open function.
  17622.  
  17623.              s     A reference to a string. Upon return, this string will
  17624.              be filled in with the line read from the file.
  17625.  
  17626.  Return Val. If the return value is greater than zero, this is the number
  17627.              of bytes placed into the string.
  17628.  
  17629.              If the return value is 0, end-of-file was encountered
  17630.  
  17631.              If the return value is -1, an error occurred when trying to
  17632.              read from the file.
  17633.  
  17634.  Description The readln function reads an entire line from the specified
  17635.              file handle. If the line ends with a newline character, it is
  17636.              automatically stripped.
  17637.  
  17638.  
  17639.  
  17640.              15. MEX Library Reference                                 320
  17641.  
  17642.  
  17643.              remove
  17644.  
  17645.  
  17646.  
  17647.  
  17648.  Prototype   int remove(string: file);
  17649.  
  17650.  Arguments   file  The name of the file to be deleted.
  17651.  
  17652.                    WARNING!
  17653.  
  17654.                    All backslashes must be escaped in MEX programs. For
  17655.                    example, to specify a file called \max\misc\foo.bbs,
  17656.                    the parameter must contain "\\max\\misc\\foo.bbs".
  17657.  
  17658.  Return Val. TRUE if the file was successfully deleted; FALSE otherwise.
  17659.  
  17660.  Description This function deletes the specified filename.
  17661.  
  17662.  
  17663.  
  17664.              rename
  17665.  
  17666.  
  17667.  
  17668.  
  17669.  Prototype   int rename(string: old, string: new);
  17670.  
  17671.  Arguments   old   The name of the file to be renamed.
  17672.  
  17673.                    WARNING!
  17674.  
  17675.                    All backslashes must be escaped in MEX programs. For
  17676.                    example, to specify a file called \max\misc\foo.bbs,
  17677.                    the parameter must contain "\\max\\misc\\foo.bbs".
  17678.  
  17679.              new   The new name to be assigned to the file.
  17680.  
  17681.  Return Val. TRUE if the rename operation was successful; FALSE otherwise.
  17682.  
  17683.  Description The rename function is used to rename or move an existing
  17684.              file. If the file is not in the current directory, full paths
  17685.              must be specified for both old and new.
  17686.  
  17687.              This function cannot be used to move files across drives.
  17688.  
  17689.  
  17690.  
  17691.              15. MEX Library Reference                                 321
  17692.  
  17693.  
  17694.              reset_more
  17695.  
  17696.  
  17697.  
  17698.  
  17699.  Prototype   void reset_more(ref char: nonstop);
  17700.  
  17701.  Arguments   nonstop   A reference to the non-stop control character. This
  17702.              character is initialized to a value of 0 by reset_more.
  17703.  
  17704.  Return Val. None
  17705.  
  17706.  Description The reset_more function resets the internal "More" counter
  17707.              that controls the number of screen lines remaining until a
  17708.              "More [Y,n,=]?" prompt is displayed. The current point in the
  17709.              display will be treated as the "top" of the current output
  17710.              page, insofar as more prompts are concerned.
  17711.  
  17712.              The nonstop variable is used in later calls to the do_more
  17713.              function (which is where the more prompts are actually dis-
  17714.              played).
  17715.  
  17716.  
  17717.  
  17718.              rip_detect
  17719.  
  17720.  
  17721.  
  17722.  
  17723.  Prototype   int rip_detect();
  17724.  
  17725.  Arguments   None
  17726.  
  17727.  Return Val. TRUE if the user's terminal supports RIPscrip graphics; FALSE
  17728.              otherwise.
  17729.  
  17730.  Description The rip_detect function is used to query the remote terminal
  17731.              to determine if it supports RIPscrip graphics. If the remote
  17732.              terminal reports that RIPscrip graphics are supported, this
  17733.              function returns TRUE.
  17734.  
  17735.              After the user has logged on, the user's current preference
  17736.              for RIPscrip graphics can be read from the usr.rip field.
  17737.  
  17738.  
  17739.  
  17740.              rip_hasfile
  17741.  
  17742.  
  17743.  
  17744.  
  17745.  Prototype   int rip_hasfile(string: fname, ref long: filesize);
  17746.  
  17747.  
  17748.  
  17749.              15. MEX Library Reference                                 322
  17750.  
  17751.  Arguments   fname The name of the remote file to query. This name must
  17752.              not have an explicit path.
  17753.  
  17754.              filesize  A reference to the size of the file to be queried.
  17755.              If filesize is set to -1, Maximus will query the remote for
  17756.              the size of the file and place it into this variable upon re-
  17757.              turn.
  17758.  
  17759.  Return Val. 1 if the remote user has the file;
  17760.              0 if the remote user does not have the file;
  17761.              -1 if a RIPscrip protocol error occurred
  17762.  
  17763.  Description The rip_hasfile function allows a MEX program to determine
  17764.              whether or not the remote user has a specified RIPscrip file.
  17765.  
  17766.              If an explicit filesize is provided, this function only re-
  17767.              turns TRUE if the remote user has the file and the file has
  17768.              the indicated size.
  17769.  
  17770.              Otherwise, if filesize is set to -1 before calling
  17771.              rip_hasfile, Maximus checks the remote side and sets the
  17772.              filesize parameter to the size of the remote file. It returns
  17773.              TRUE if the file exists and FALSE otherwise.
  17774.  
  17775.  
  17776.  
  17777.              rip_send
  17778.  
  17779.  
  17780.  
  17781.  
  17782.  Prototype   int rip_send(string: filename, int: display);
  17783.  
  17784.  Arguments   filename  The filename to be sent to the remote RIPscrip
  17785.              user. If no path is specified, Maximus will assume the cur-
  17786.              rent RIP Path.
  17787.  
  17788.              display   TRUE if the file is to be displayed as soon as it
  17789.              is sent; FALSE otherwise.
  17790.  
  17791.  Return Val. TRUE if the file was successfully displayed/sent; FALSE oth-
  17792.              erwise.
  17793.  
  17794.  Description This function is used to send a RIPscrip scene or icon file
  17795.              to the remote user. After sending the file, it can be option-
  17796.              ally displayed by setting the display parameter to TRUE.
  17797.  
  17798.              This performs a function equivalent to the [ripsend] MECCA
  17799.              token.
  17800.  
  17801.  
  17802.  
  17803.              15. MEX Library Reference                                 323
  17804.  
  17805.  
  17806.              screen_length
  17807.  
  17808.  
  17809.  
  17810.  
  17811.  Prototype   int screen_length();
  17812.  
  17813.  Arguments   None
  17814.  
  17815.  Return Val. The length of the local screen, in rows.
  17816.  
  17817.  Description The screen_length function returns the length of the local
  17818.              console screen.
  17819.  
  17820.  
  17821.  
  17822.              screen_width
  17823.  
  17824.  
  17825.  
  17826.  
  17827.  Prototype   int screen_width();
  17828.  
  17829.  Arguments   None
  17830.  
  17831.  Return Val. The width of the local screen, in columns.
  17832.  
  17833.  Description The screen_width function returns the width of the local con-
  17834.              sole screen.
  17835.  
  17836.  
  17837.  
  17838.              seek
  17839.  
  17840.  
  17841.  
  17842.  
  17843.  Prototype   int seek(int: fd, long: pos, int: where);
  17844.  
  17845.  Arguments   fd    A file descriptor, as returned by the open function.
  17846.  
  17847.              pos   The position to which the file should be seeked. This
  17848.              position is relative to the offset specified for the where
  17849.              parameter. Negative offsets are permitted if either SEEK_CUR
  17850.              or SEEK_END are specified for where.
  17851.  
  17852.              where This parameter defines the relation between the pos pa-
  17853.              rameter and the physical offset within the file. This is de-
  17854.              scribed in more detail below.
  17855.  
  17856.  Return Val. The new file offset, relative to the beginning of the file.
  17857.  
  17858.  
  17859.  
  17860.              15. MEX Library Reference                                 324
  17861.  
  17862.  Description The seek function moves the file pointer for the specified
  17863.              file to a new location. This function is used to jump to an
  17864.              arbitrary offset within a file, or to jump directly to the
  17865.              beginning or end of a file.
  17866.  
  17867.              The where parameter must be one of the values from Table
  17868.              15.41:
  17869.  
  17870.              Table 15.41 Seek Offsets
  17871.  
  17872.               Value    Description
  17873.  
  17874.               SEEK_CUR pos is relative to the current file position.
  17875.               SEEK_SET pos is relative to the beginning of the file.
  17876.               SEEK_END pos is relative to the end of the file.
  17877.  
  17878.  
  17879.  
  17880.  
  17881.              set_output
  17882.  
  17883.  
  17884.  
  17885.  
  17886.  Prototype   int set_output(int mode);
  17887.  
  17888.  Arguments   mode  This function sets the output control mode. This must
  17889.              be one of the DISABLE_* parameters described below.
  17890.  
  17891.  Return Val. The original setting for screen output. This return value can
  17892.              be used to restore the screen output mode at a later time by
  17893.              calling set_output again.
  17894.  
  17895.  Description This function allows the Maximus video output to be sup-
  17896.              pressed, for either the remote user, the local screen, or
  17897.              both.
  17898.  
  17899.              The mode parameter must be one of the values from Table
  17900.              15.42:
  17901.  
  17902.              Table 15.42 Output Disable Modes
  17903.  
  17904.               Value            Description
  17905.  
  17906.               DISABLE_NONE     Enable all output.
  17907.               DISABLE_LOCAL    Disable only local output.
  17908.               DISABLE_REMOTE   Disable only remote output.
  17909.               DISABLE_BOTH     Disable both local and remote output.
  17910.  
  17911.  
  17912.  
  17913.              15. MEX Library Reference                                 325
  17914.  
  17915.  
  17916.              set_static_data
  17917.  
  17918.  
  17919.  
  17920.  
  17921.  Prototype   int set_static_data(string: key, ref void: data);
  17922.  
  17923.  Arguments   key   The key for the static data object to be set. This must
  17924.              be the same as the key parameter passed to cre-
  17925.              ate_static_data.
  17926.  
  17927.              data  A reference to the local data object to store in the
  17928.              static data object. Note that this parameter is a void refer-
  17929.              ence, meaning that any type of object (char, int, long, array
  17930.              or struct) can be referenced.
  17931.  
  17932.  Return Val. 0 if the data object was stored successfully;
  17933.              -1 if the key name was not found.
  17934.  
  17935.  Description The set_static_data function is used to store data that can
  17936.              be retrieved later during the same Maximus session by the
  17937.              get_static_data function. Data stored by set_static_data is
  17938.              persistent, in that it retains its value even after the cre-
  17939.              ating MEX program has ended.
  17940.  
  17941.              If key is a valid static data key that was created by cre-
  17942.              ate_static_data, this function will copy the information from
  17943.              the local structure referenced by data into the static data
  17944.              object.
  17945.  
  17946.  
  17947.  
  17948.              set_static_string
  17949.  
  17950.  
  17951.  
  17952.  
  17953.  Prototype   int set_static_string(string: key, string: data);
  17954.  
  17955.  Arguments   key   The key for the static string to be set. This must be
  17956.              the same as the key parameter passed to create_static_string.
  17957.  
  17958.              data  The local string to be stored in the static string.
  17959.  
  17960.  Return Val. 0 if the string was stored successfully;
  17961.              -1 if the key name was not found;
  17962.              -2 if there was not enough memory to store the string.
  17963.  
  17964.  Description The set_static_string function is used to store strings that
  17965.              can be retrieved later during the same Maximus session by the
  17966.              get_static_string function. Strings stored by
  17967.  
  17968.  
  17969.  
  17970.              15. MEX Library Reference                                 326
  17971.  
  17972.              set_static_string are persistent, in that they retain their
  17973.              values even after the creating MEX program has ended.
  17974.  
  17975.              If key is a valid static string key that was created by cre-
  17976.              ate_static_string, this function will copy the information
  17977.              from the local string referenced by data into the static
  17978.              string.
  17979.  
  17980.  
  17981.  
  17982.              set_textsize
  17983.  
  17984.  
  17985.  
  17986.  
  17987.  Prototype   void set_textsize(int: cols, int: rows);
  17988.  
  17989.  Arguments   cols  The number of columns in the window.
  17990.  
  17991.              rows  The number of rows in the window.
  17992.  
  17993.  Return Val. None
  17994.  
  17995.  Description The set_textsize sets the assumed text window size of the re-
  17996.              mote system. This is primarily used to set the size of the
  17997.              display for "More" prompting when using RIPscrip windows on
  17998.              the remote terminal.
  17999.  
  18000.              Specifying values of 0 for either cols or rows will set the
  18001.              window width or length (respectively) back to the default, as
  18002.              specified in the user record.
  18003.  
  18004.  
  18005.  
  18006.              shell
  18007.  
  18008.  
  18009.  
  18010.  
  18011.  Prototype   int shell(int: method, string: cmd);
  18012.  
  18013.  Arguments   methodAn IOUTSIDE_* constant describing the method to use for
  18014.              executing the program. This parameter is described below in
  18015.              more detail.
  18016.  
  18017.              cmd   The name of the command to run, plus any optional pro-
  18018.              gram arguments.
  18019.  
  18020.                    WARNING!
  18021.  
  18022.                    All backslashes must be escaped in MEX programs. For
  18023.                    example, to specify a file called \max\misc\foo.bbs,
  18024.                    the parameter must contain "\\max\\misc\\foo.bbs".
  18025.  
  18026.  
  18027.  
  18028.              15. MEX Library Reference                                 327
  18029.  
  18030.  Return Val. The return value of the program, or -1 if the program could
  18031.              not be executed.
  18032.  
  18033.  Description The shell function invokes an external program or a secondary
  18034.              copy of the command interpreter. The exact method used for
  18035.              invoking the external program depends on the value of the
  18036.              method parameter. At least one of IOUTSIDE_RUN or IOUT-
  18037.              SIDE_DOS must be specified; the other parameters from Table
  18038.              15.43 are optional and can be combined using the bitwise or
  18039.              operator:
  18040.  
  18041.              Table 15.43 Outside Methods
  18042.  
  18043.               Value               Description
  18044.  
  18045.               IOUTSIDE_RUN        Spawn the program directly. This op-
  18046.                                   tion can only be used to run .exe and
  18047.                                   .com files in the operating system's
  18048.                                   native format. This method is faster
  18049.                                   than IOUTSIDE_DOS.
  18050.               IOUTSIDE_DOS        Execute the program through the com-
  18051.                                   mand interpreter. This option can be
  18052.                                   used to spawn .bat, .cmd. ,exe and
  18053.                                   .com files, in addition to internal
  18054.                                   shell commands (such as "dir" and
  18055.                                   "copy"). Under OS/2, this function can
  18056.                                   also be used to invoke DOS programs.
  18057.               IOUTSIDE_REREAD     After running the external program,
  18058.                                   re-read the user record from the las-
  18059.                                   tuser.bbs file. This flag can be com-
  18060.                                   bined with the IOUTSIDE_RUN or IOUT-
  18061.                                   SIDE_DOS flags using the bitwise or
  18062.                                   operator.
  18063.  
  18064.  
  18065.  
  18066.  Example     The following code displays a directory of the \MAX\MISC di-
  18067.              rectory:
  18068.  
  18069.                 shell(IOUTSIDE_DOS, "dir c:\\max\\misc");
  18070.  
  18071.  
  18072.              sleep
  18073.  
  18074.  
  18075.  
  18076.  
  18077.  Prototype   void sleep(int: duration);
  18078.  
  18079.  Arguments   duration  The amount of time to sleep, measured in hundredths
  18080.              of seconds.
  18081.  
  18082.  Return Val. None
  18083.  
  18084.  
  18085.  
  18086.              15. MEX Library Reference                                 328
  18087.  
  18088.  Description The sleep function instructs Maximus to pause for a certain
  18089.              period of time. Since duration is measured in hundredths of
  18090.              seconds, a value of 500 would tell Maximus to sleep for five
  18091.              seconds.
  18092.  
  18093.              Under OS/2, this function can be used to temporarily yield
  18094.              control to other programs during a polling loop. Calling
  18095.              sleep(1) tells Maximus to yield for long enough for other
  18096.              programs to run, but also to return control to the MEX pro-
  18097.              gram quickly enough so that there is no noticeable lag in re-
  18098.              sponse time.
  18099.  
  18100.  
  18101.  
  18102.              snoop
  18103.  
  18104.  
  18105.  
  18106.  
  18107.  Prototype   int snoop(int: state);
  18108.  
  18109.  Arguments   state The new state for the console snoop mode. A value of
  18110.              TRUE enables snoop mode, while a value of FALSE disables
  18111.              snoop mode.
  18112.  
  18113.  Return Val. The original setting of snoop mode. This value can be used at
  18114.              a later time to restore the original snoop mode setting.
  18115.  
  18116.  Description The snoop function is used to set the state of the internal
  18117.              "snoop" feature. When snoop is enabled, the local console
  18118.              will show exactly what is displayed on the remote screen.
  18119.  
  18120.  
  18121.  
  18122.              stamp_string
  18123.  
  18124.  
  18125.  
  18126.  
  18127.  Prototype   string stamp_string(ref struct _stamp: t);
  18128.  
  18129.  Arguments   t     A reference to a structure containing date and time
  18130.              values.
  18131.  
  18132.  Return Val. A string version of the date and time, using the format
  18133.              specified in max.ctl.
  18134.  
  18135.  Description The stamp_string function converts a _stamp structure into a
  18136.              human-readable string, using the SysOp-defined time format in
  18137.              the max.ctl file.
  18138.  
  18139.  
  18140.  
  18141.              15. MEX Library Reference                                 329
  18142.  
  18143.  
  18144.              stamp_to_long
  18145.  
  18146.  
  18147.  
  18148.  
  18149.  Prototype   long stamp_to_long(ref struct _stamp: st);
  18150.  
  18151.  Arguments   st    A reference to a structure containing date and time
  18152.              values.
  18153.  
  18154.  Return Val. A long integer representing the number of seconds elapsed
  18155.              since January 1st, 1970 UTC.
  18156.  
  18157.  Description The stamp_to_long function converts a _stamp structure back
  18158.              into the format that is returned by the time function. This
  18159.              function is useful when the date/time entries into two _stamp
  18160.              structures need to be compared in terms of chronological or-
  18161.              der.
  18162.  
  18163.  
  18164.  
  18165.              strfind
  18166.  
  18167.  
  18168.  
  18169.  
  18170.  Prototype   int strfind(ref string: str, string: substring);
  18171.  
  18172.  Arguments   stringThe string to be searched.
  18173.  
  18174.              substring The substring to search for within string.
  18175.  
  18176.  Return Val. 0 if substring was not found; otherwise, the index in string
  18177.              at which substring is found. An index of 1 indicates the
  18178.              first byte in string.
  18179.  
  18180.  Description The strfind function tries to find an occurrence of substring
  18181.              within the master string str.
  18182.  
  18183.  Example     This shows how the strfind return value is used:
  18184.  
  18185.                 #include <max.mh>
  18186.  
  18187.                 int main()
  18188.                 {
  18189.                   int: i;
  18190.  
  18191.                   i := strfind("This is a big string", "big");
  18192.                   print(i); // i = 11
  18193.                   return 0;
  18194.                 }
  18195.  
  18196.  
  18197.  
  18198.              15. MEX Library Reference                                 330
  18199.  
  18200.  
  18201.              stridx
  18202.  
  18203.  
  18204.  
  18205.  
  18206.  Prototype   int stridx(string: src, int: startpos, int: ch);
  18207.  
  18208.  Arguments   src   The string to be searched.
  18209.  
  18210.              startpos  The position in src at which the search is to
  18211.              start.
  18212.  
  18213.              ch    The character to search for within src.
  18214.  
  18215.  Return Val. 0 if the character could not be found; otherwise, the index
  18216.              of the position containing the character.
  18217.  
  18218.  Description The stridx function searches the string specified by src for
  18219.              any occurrences of the character ch. If ch is found, it re-
  18220.              turns the index of that character within the string.
  18221.  
  18222.              This function searches the string from left to right, start-
  18223.              ing at the position specified. To search the string from
  18224.              right to left, see the strridx function.
  18225.  
  18226.  Example     To search for all instances of a character within a given
  18227.              string, the following code can be used:
  18228.  
  18229.                 #include <max.mh>
  18230.  
  18231.                 int main()
  18232.                 {
  18233.                   int: pos;
  18234.                   string: src;
  18235.  
  18236.                   src := "Abcdxefghxijklmnoxpqxrxxst";
  18237.                   pos := 1;
  18238.  
  18239.                   for (pos := stridx (src, pos, 'x');
  18240.                        pos;
  18241.                        pos := stridx (src, pos+1, 'x'))
  18242.                   {
  18243.                        print("Found an 'x' at position ",
  18244.                              pos, '\n');
  18245.                   }
  18246.  
  18247.                   return 0;
  18248.                 }
  18249.  
  18250.  
  18251.  
  18252.              15. MEX Library Reference                                 331
  18253.  
  18254.  
  18255.              strlen
  18256.  
  18257.  
  18258.  
  18259.  
  18260.  Prototype   int strlen(string: s);
  18261.  
  18262.  Arguments   s     The string to be measured.
  18263.  
  18264.  Return Val. The length of the string.
  18265.  
  18266.  Description The strlen function determines the length of a given string
  18267.              and returns it to the caller.
  18268.  
  18269.              An empty or uninitialized string has a length of 0.
  18270.  
  18271.  
  18272.  
  18273.              strlower
  18274.  
  18275.  
  18276.  
  18277.  
  18278.  Prototype   string strlower(string: src);
  18279.  
  18280.  Arguments   src   The string to be converted.
  18281.  
  18282.  Return Val. A lowercase version of the src string.
  18283.  
  18284.  Description This function converts a string to lowercase.
  18285.  
  18286.  
  18287.  
  18288.              strpad
  18289.  
  18290.  
  18291.  
  18292.  
  18293.  Prototype   string strpad(string: str, int: length, char: pad);
  18294.  
  18295.  Arguments   str   The string to be padded
  18296.  
  18297.              lengthThe length to which the string should be padded.
  18298.  
  18299.              pad   The character which should be used for padding the
  18300.              string.
  18301.  
  18302.  Return Val. The padded version of the string.
  18303.  
  18304.  Description The strpad function pads a string so that it is at least
  18305.              length characters long.
  18306.  
  18307.  
  18308.  
  18309.              15. MEX Library Reference                                 332
  18310.  
  18311.              If the string is already more than or equal to length charac-
  18312.              ters in length, the string is returned unchanged.
  18313.  
  18314.              If the string is less than length characters in length, the
  18315.              pad character is appended to the end of the string as many
  18316.              times as necessary to make the string exactly length charac-
  18317.              ters long.
  18318.  
  18319.  
  18320.  
  18321.              strpadleft
  18322.  
  18323.  
  18324.  
  18325.  
  18326.  Prototype   string strpadleft(string: str, int: length, char: pad);
  18327.  
  18328.  Arguments   str   The string to be padded
  18329.  
  18330.              lengthThe length to which the string should be padded.
  18331.  
  18332.              pad   The character which should be used for padding the
  18333.              string.
  18334.  
  18335.  Return Val. The padded version of the string.
  18336.  
  18337.  Description The strpadleft function pads a string so that it is at least
  18338.              length characters long.
  18339.  
  18340.              This function differs from strpad only in that the padding
  18341.              characters are added to the beginning of the string rather
  18342.              than at the end of the string.
  18343.  
  18344.  
  18345.  
  18346.              strridx
  18347.  
  18348.  
  18349.  
  18350.  
  18351.  Prototype   int strridx(string: src, int: startpos, int: ch);
  18352.  
  18353.  Arguments   src   The string to be searched.
  18354.  
  18355.              startpos  The position in src at which the search is to
  18356.              start. A value of 0 for startpos instructs Maximus to start
  18357.              searching from the end of the string.
  18358.  
  18359.              ch    The character to search for within src.
  18360.  
  18361.  Return Val. 0 if the character could not be found; otherwise, the index
  18362.              of the position containing the character.
  18363.  
  18364.  
  18365.  
  18366.              15. MEX Library Reference                                 333
  18367.  
  18368.  Description The strridx function searches the string specified by src for
  18369.              any occurrences of the character ch. If ch is found, it re-
  18370.              turns the index of that character within the string.
  18371.  
  18372.              This function searches the string from right to left, start-
  18373.              ing at the position specified, or at the end of the string if
  18374.              startpos is 0. To search the string from left to right, see
  18375.              the stridx function.
  18376.  
  18377.  Example     To search for all instances of a character within a given
  18378.              string, the following code can be used. (The character indi-
  18379.              ces are returned in order from right to left.)
  18380.  
  18381.                 #include <max.mh>
  18382.  
  18383.                 int main()
  18384.                 {
  18385.                   string: src;
  18386.                   int: pos;
  18387.  
  18388.                   src := "Abcdxefgxijklmnxxopqxrxstux";
  18389.                   pos := 0;
  18390.  
  18391.                   for (pos := strridx(src, pos, 'x');
  18392.                        pos;
  18393.                        pos := strridx(src, pos-1, 'x'))
  18394.                   {
  18395.                        print("Found an 'x' at position ",
  18396.                              pos, '\n');
  18397.                   }
  18398.  
  18399.                   return 0;
  18400.                 }
  18401.  
  18402.  
  18403.              strtoi
  18404.  
  18405.  
  18406.  
  18407.  
  18408.  Prototype   int strtoi(string: s);
  18409.  
  18410.  Arguments   s     The string containing the decimal representation of a
  18411.              number.
  18412.  
  18413.  Return Val. The integer equivalent of the string, or 0 if the string
  18414.              could not be converted.
  18415.  
  18416.  Description The strtoi function converts an ASCII string into an integer.
  18417.              The string must have a digit as its first character, and the
  18418.              number represented in the string must be in decimal.
  18419.  
  18420.  
  18421.  
  18422.              15. MEX Library Reference                                 334
  18423.  
  18424.              This function reads the string until it encounters a non-
  18425.              digit or the end of the string. All of the digits up to that
  18426.              point are converted and returned to the caller as an integer.
  18427.  
  18428.              This function can handle numbers in the range of -32768
  18429.              through 65535. However, the exact range of usable numbers de-
  18430.              pends on the type of integer to which the return code is as-
  18431.              signed.
  18432.  
  18433.              If the return code is assigned to an unsigned integer, values
  18434.              in the range 0 to 65535 are converted. Otherwise, if the re-
  18435.              turn code is assigned to a signed integer, values in the
  18436.              range -32768 to 32767 are converted. To handle larger num-
  18437.              bers, see the strtol function.
  18438.  
  18439.  
  18440.  
  18441.              strtok
  18442.  
  18443.  
  18444.  
  18445.  
  18446.  Prototype   int strtok(string: src, string: toks, ref int: pos);
  18447.  
  18448.  Arguments   src   The source string to be tokenized.
  18449.  
  18450.              toks  A string containing a list of acceptable token delimit-
  18451.              ers. These token delimiters are used to delimit where one to-
  18452.              ken ends and the following token begins. The end of the
  18453.              string is always considered to be a delimiter.
  18454.  
  18455.              pos   A reference to an integer containing the most-recently
  18456.              examined position in the string. On the initial call to
  18457.              strtok, this value should be set to 0. This variable is nor-
  18458.              mally updated by strtok, so applications should not need to
  18459.              modify pos after the first call to strtok.
  18460.  
  18461.  Return Val. A string containing the token, stripped of all token delimit-
  18462.              ers. If no more tokens exist in the string, the null string
  18463.              ("") is returned.
  18464.  
  18465.  Description The strtok function is used for parsing strings. It returns
  18466.              the substring in src, starting at position pos, which is de-
  18467.              limited by any of the characters in the toks string.
  18468.  
  18469.  Example     The following code tokenizes a string, using spaces and tabs
  18470.              as delimiters:
  18471.  
  18472.                 #include <max.mh>
  18473.  
  18474.                 int main()
  18475.                 {
  18476.                   string: src, sub;
  18477.  
  18478.  
  18479.  
  18480.              15. MEX Library Reference                                 335
  18481.  
  18482.                   int: pos;
  18483.  
  18484.                   pos := 0;
  18485.                   src := "This is a test";
  18486.  
  18487.                   for (sub := strtok (src, " \t", pos);
  18488.                        sub <> "";
  18489.                        sub := strtok (src, " \t", pos))
  18490.                   {
  18491.                        print("Word is '", sub, "'\n");
  18492.                   }
  18493.  
  18494.                   // The program prints:
  18495.                   //
  18496.                   // Word is 'This'
  18497.                   // Word is 'is'
  18498.                   // Word is 'a'
  18499.                   // Word is 'test'
  18500.  
  18501.                   return 0;
  18502.                 }
  18503.  
  18504.  
  18505.  
  18506.              strtol
  18507.  
  18508.  
  18509.  
  18510.  
  18511.  Prototype   int strtol(string: s);
  18512.  
  18513.  Arguments   s     The string containing the decimal representation of a
  18514.              number.
  18515.  
  18516.  Return Val. The long integer equivalent of the string, or 0 if the string
  18517.              could not be converted.
  18518.  
  18519.  Description The strtol function converts an ASCII string into a long in-
  18520.              teger. The string must have a digit as its first character,
  18521.              and the number represented in the string must be in decimal.
  18522.  
  18523.              This function reads the string until it encounters a non-
  18524.              digit or the end of the string. All of the digits up to that
  18525.              point are converted and returned to the caller.
  18526.  
  18527.              This function can handle numbers in the range of -2147483648
  18528.              to 4294967296. However, the exact range of usable numbers de-
  18529.              pends on the type of long integer to which the return code is
  18530.              assigned.
  18531.  
  18532.              If the return code is assigned to an unsigned long, values in
  18533.              the range 0 to 4294967296 are converted. Otherwise, if the
  18534.  
  18535.  
  18536.  
  18537.              15. MEX Library Reference                                 336
  18538.  
  18539.              return code is assigned to a signed integer, values in the
  18540.              range -2147483648 to 2147483647 are converted.
  18541.  
  18542.  
  18543.  
  18544.              strtrim
  18545.  
  18546.  
  18547.  
  18548.  
  18549.  Prototype   string strtrim(string: src, string: chrs);
  18550.  
  18551.  Arguments   src   The string to be trimmed.
  18552.  
  18553.              chrs  A string containing a list of characters to be trimmed
  18554.              from the beginning and end of src.
  18555.  
  18556.  Return Val. The trimmed string.
  18557.  
  18558.  Description The strtrim function adjusts a string to remove leading and
  18559.              trailing characters specified in the chrs string. The re-
  18560.              turned string contains a copy of the original string with the
  18561.              leading and trailing characters stripped.
  18562.  
  18563.  Example     This code demonstrates the usage of the strtrim function:
  18564.  
  18565.                 string: trimmed;
  18566.  
  18567.                 trimmed := strtrim("What to do now?", "Wh?");
  18568.                 // trimmed contains "at to do now"
  18569.  
  18570.  
  18571.              strupper
  18572.  
  18573.  
  18574.  
  18575.  
  18576.  Prototype   string strupper(string: src);
  18577.  
  18578.  Arguments   src   The string to be converted.
  18579.  
  18580.  Return Val. An uppercase version of the src string.
  18581.  
  18582.  Description This function converts a string to uppercase.
  18583.  
  18584.  
  18585.  
  18586.              substr
  18587.  
  18588.  
  18589.  
  18590.  
  18591.  Prototype   string substr(string: s, int: pos, int: length);
  18592.  
  18593.  
  18594.  
  18595.              15. MEX Library Reference                                 337
  18596.  
  18597.  Arguments   s     The  source string from which the substring is to be
  18598.              extracted.
  18599.  
  18600.              pos   The starting position within s from which the substring
  18601.              is to be taken. A value of 1 specifies the first character in
  18602.              s.
  18603.  
  18604.              lengthThe maximum length of the substring to be extracted
  18605.              from s. The substr function will normally extract exactly
  18606.              length characters, but if this character count would exceed
  18607.              the length of the string, fewer characters will be extracted.
  18608.  
  18609.  Return Val. The substring extracted from s.
  18610.  
  18611.  Description The substr function extracts a substring from the source
  18612.              string s. The substring is defined by specifying a starting
  18613.              position within the string, and also by specifying the number
  18614.              of following characters which are to be taken as part of that
  18615.              substring.
  18616.  
  18617.  Example     This code shows how the substr function operates:
  18618.  
  18619.                 #include <max.mh>
  18620.  
  18621.                 int main()
  18622.                 {
  18623.                   string: str;
  18624.  
  18625.                   str := substr("The quick brown fox", 11, 5);
  18626.  
  18627.                   print(str); // str now contains "brown"
  18628.                   return 0;
  18629.                 }
  18630.  
  18631.  
  18632.  
  18633.              tag_dequeue_file
  18634.  
  18635.  
  18636.  
  18637.  
  18638.  Prototype   int tag_dequeue_file(int: posn);
  18639.  
  18640.  Arguments   posn  Position of the file within the tag list. The first
  18641.              file in the list is position 0.
  18642.  
  18643.  Return Val. TRUE if the file was successfully dequeued; FALSE otherwise.
  18644.  
  18645.  Description The tag_dequeue_file function is used to remove files from
  18646.              the internal queue of files to be downloaded.
  18647.  
  18648.  
  18649.  
  18650.              15. MEX Library Reference                                 338
  18651.  
  18652.              The number of files in the queue can be obtained using the
  18653.              tag_queue_size function, and information about specific queue
  18654.              entries can be obtained using the tag_get_name function.
  18655.  
  18656.  
  18657.  
  18658.              tag_get_name
  18659.  
  18660.  
  18661.  
  18662.  
  18663.  Prototype   int tag_get_name(int: posn, ref int: flags, ref string: file-
  18664.              name);
  18665.  
  18666.  Arguments   posn  Position of the file within the tag list. The first
  18667.              file in the list is position 0.
  18668.  
  18669.              flags Upon return, this variable is updated with a copy of
  18670.              the flags indicating the attributes for the file. These at-
  18671.              tributes are described in more detail in the tag_queue_file
  18672.              function.
  18673.  
  18674.              filename  A reference to a string. Upon return, this string
  18675.              is updated with the full filename and path of the file in the
  18676.              specified queue position.
  18677.  
  18678.  Return Val. TRUE if the file information was successfully queried; FALSE
  18679.              otherwise.
  18680.  
  18681.  Description The tag_get_name function is used to determine the names and
  18682.              attributes of files in the download queue.
  18683.  
  18684.  
  18685.  
  18686.              tag_queue_file
  18687.  
  18688.  
  18689.  
  18690.  
  18691.  Prototype   int tag_queue_file(string: filename, int: flags);
  18692.  
  18693.  Arguments   filename  The full path and filename of the file to be added
  18694.              to the queue.
  18695.  
  18696.                    WARNING!
  18697.  
  18698.                    All backslashes must be escaped in MEX programs. For
  18699.                    example, to specify a file called \max\misc\foo.bbs,
  18700.                    the parameter must contain "\\max\\misc\\foo.bbs".
  18701.  
  18702.              flags A list of zero or more FFLAG_* file attributes to be
  18703.              assigned to this file. Multiple attributes can be combined
  18704.              using the bitwise or operator.
  18705.  
  18706.  
  18707.  
  18708.              15. MEX Library Reference                                 339
  18709.  
  18710.  Return Val. TRUE if the file was successfully queued; FALSE otherwise.
  18711.  
  18712.  Description The tag_queue_file inserts a specific file into the user's
  18713.              download queue. The full path and filename of the file must
  18714.              be given. In addition, a number of optional flags from Table
  18715.              15.44 can be set to describe the file being downloaded:
  18716.  
  18717.              Table 15.44 File Queue Flags
  18718.  
  18719.               Flag             Description
  18720.  
  18721.               FFLAG_NOTIME     The file is not counted against the user's
  18722.                                time limit.
  18723.               FFLAG_NOBYTES    The file is not counted against the user's
  18724.                                file download limit.
  18725.               FFLAG_STAGE      The file is to be copied to the staging
  18726.                                path before being sent to the user, as is
  18727.                                typically done for CD-ROM drives.
  18728.               FFLAG_SLOW       The file is on slow media, so Maximus will
  18729.                                try not to access the drive any more than
  18730.                                necessary.
  18731.  
  18732.  
  18733.  
  18734.              tag_queue_size
  18735.  
  18736.  
  18737.  
  18738.  
  18739.  Prototype   int tag_queue_size();
  18740.  
  18741.  Arguments   None
  18742.  
  18743.  Return Val. The number of files in the download queue.
  18744.  
  18745.  Description This function returns the number of files that are currently
  18746.              in the download queue. The other tag_* functions use zero-
  18747.              based position numbers, so a queue containing 5 files will
  18748.              have file entries at positions 0, 1, 2, 3 and 4.
  18749.  
  18750.  
  18751.  
  18752.              tell
  18753.  
  18754.  
  18755.  
  18756.  
  18757.  Prototype   long tell(int: fd);
  18758.  
  18759.  Arguments   fd    A file descriptor, as returned by the open function.
  18760.  
  18761.  Return Val. The position within the file where the next read, readln,
  18762.              write, or writeln will take place.
  18763.  
  18764.  
  18765.  
  18766.              15. MEX Library Reference                                 340
  18767.  
  18768.  Description The tell function is used to determine the current offset of
  18769.              a file.
  18770.  
  18771.  
  18772.  
  18773.              term_length
  18774.  
  18775.  
  18776.  
  18777.  
  18778.  Prototype   int term_length();
  18779.  
  18780.  Arguments   None
  18781.  
  18782.  Return Val. The length of the user's terminal (in rows).
  18783.  
  18784.  Description The term_length function returns the current length of the
  18785.              user's terminal. If a set_textsize call has been made, the
  18786.              length parameter passed to that function is returned here.
  18787.              Otherwise, the value from the user record is returned.
  18788.  
  18789.  
  18790.  
  18791.              term_width
  18792.  
  18793.  
  18794.  
  18795.  
  18796.  Prototype   int term_width();
  18797.  
  18798.  Arguments   None
  18799.  
  18800.  Return Val. The width of the user's terminal (in columns).
  18801.  
  18802.  Description The term_width function returns the current width of the
  18803.              user's terminal. If a set_textsize call has been made, the
  18804.              width parameter passed to that function is returned here.
  18805.              Otherwise, the value from the user record is returned.
  18806.  
  18807.  
  18808.  
  18809.              time
  18810.  
  18811.  
  18812.  
  18813.  
  18814.  Prototype   long time();
  18815.  
  18816.  Arguments   None
  18817.  
  18818.  Return Val. The number of seconds elapsed since January 1st 1970 (UTC).
  18819.  
  18820.  Description This function returns the current value of the system timer.
  18821.  
  18822.  
  18823.  
  18824.              15. MEX Library Reference                                 341
  18825.  
  18826.  
  18827.              time_check
  18828.  
  18829.  
  18830.  
  18831.  
  18832.  Prototype   int time_check(int: state);
  18833.  
  18834.  Arguments   state The new state for time checking. If TRUE, time checking
  18835.              is enabled. Otherwise, time checking is disabled.
  18836.  
  18837.  Return Val. The original time checking state. This returns TRUE if the
  18838.              time checking was enabled prior to this function call; FALSE
  18839.              otherwise. This value can be used to restore the original
  18840.              time checking state at a later time.
  18841.  
  18842.  Description The time_check function is used to enable or disable time
  18843.              checking. Disabling time checking effectively "freezes" the
  18844.              user timer countdown, which would be desirable when writing a
  18845.              MEX-based chat program or call-back verifier.
  18846.  
  18847.  
  18848.  
  18849.              timeadjust
  18850.  
  18851.  
  18852.  
  18853.  
  18854.  Prototype   long timeadjust(long: delta);
  18855.  
  18856.  Arguments   delta The number of seconds to be added to the user's current
  18857.              time limit. A negative value for delta indicates that the
  18858.              user's time limit is to be decreased by the indicated amount.
  18859.  
  18860.  Return Val. The user's new time limit, measured in seconds.
  18861.  
  18862.  Description The timeadjust function is used to adjust the user's current
  18863.              time limit. Note that this function disregards the event file
  18864.              and the -t command line parameter. If this function is used
  18865.              blindly, the user could easily be allowed to overrun a sched-
  18866.              uled event.
  18867.  
  18868.              To get the user's current time limit measured in seconds,
  18869.              call timeadjust(0).
  18870.  
  18871.  
  18872.  
  18873.              timeadjustsoft
  18874.  
  18875.  
  18876.  
  18877.  
  18878.  Prototype   long timeadjustsoft(long: delta);
  18879.  
  18880.  
  18881.  
  18882.              15. MEX Library Reference                                 342
  18883.  
  18884.  Arguments   delta The number of seconds to be added to the user's current
  18885.              time limit. A negative value for delta indicates that the
  18886.              user's time limit is to be decreased by the indicated amount.
  18887.  
  18888.  Return Val. The user's new time limit, measured in seconds.
  18889.  
  18890.  Description The timeadjustsoft function is used to adjust the user's cur-
  18891.              rent time limit. This function will not allow the user's time
  18892.              limit to be adjusted to exceed an external event.
  18893.  
  18894.  
  18895.  
  18896.              timeleft
  18897.  
  18898.  
  18899.  
  18900.  
  18901.  Prototype   long timeleft();
  18902.  
  18903.  Arguments   None
  18904.  
  18905.  Return Val. The user's remaining time limit, in minutes.
  18906.  
  18907.  Description The timeleft function returns a value indicating the length
  18908.              of time that the current user is allowed to stay on-line, in
  18909.              minutes.
  18910.  
  18911.  
  18912.  
  18913.              timeon
  18914.  
  18915.  
  18916.  
  18917.  
  18918.  Prototype   long timeon();
  18919.  
  18920.  Arguments   None
  18921.  
  18922.  Return Val. The number of minutes that the user has been logged on.
  18923.  
  18924.  Description The timeon function returns the amount of time elapsed for
  18925.              the current call, in minutes.
  18926.  
  18927.  
  18928.  
  18929.              timestamp
  18930.  
  18931.  
  18932.  
  18933.  
  18934.  Prototype   void timestamp(ref struct _stamp: stamp);
  18935.  
  18936.  
  18937.  
  18938.              15. MEX Library Reference                                 343
  18939.  
  18940.  Arguments   stamp A reference to a _stamp structure. Upon return, this
  18941.              structure will be updated with a copy of the current date and
  18942.              time.
  18943.  
  18944.  Return Val. None
  18945.  
  18946.  Description This function retrieves the current date and time.
  18947.  
  18948.  
  18949.  
  18950.              uitostr
  18951.  
  18952.  
  18953.  
  18954.  
  18955.  Prototype   string uitostr(unsigned int: i);
  18956.  
  18957.  Arguments   i     The unsigned integer to be converted.
  18958.  
  18959.  Return Val. This function returns the string representation of the un-
  18960.              signed integer.
  18961.  
  18962.  Description The itostr function is used to convert an unsigned integer to
  18963.              a string. The converted string contains the ASCII representa-
  18964.              tion of the integer, from 0 to 65535. See the itostr function
  18965.              for converting signed integers.
  18966.  
  18967.              This function is useful when strings must be mixed with the
  18968.              results of integral computations.
  18969.  
  18970.  
  18971.  
  18972.              ultostr
  18973.  
  18974.  
  18975.  
  18976.  
  18977.  Prototype   string ultostr(unsigned long: l);
  18978.  
  18979.  Arguments   l     The unsigned long integer to be converted.
  18980.  
  18981.  Return Val. This function returns the string representation of the long
  18982.              integer.
  18983.  
  18984.  Description The ultostr function is used to convert an unsigned long in-
  18985.              teger to a string. The converted string contains the ASCII
  18986.              representation of the unsigned long integer, from 0 to
  18987.              4294967295. See the ltostr function for converting signed
  18988.              longs.
  18989.  
  18990.              This function is useful when strings must be mixed with the
  18991.              results of integral computations.
  18992.  
  18993.  
  18994.  
  18995.              15. MEX Library Reference                                 344
  18996.  
  18997.  Example     See the description for the itostr function for a related ex-
  18998.              ample.
  18999.  
  19000.  
  19001.  
  19002.              usercreate
  19003.  
  19004.  
  19005.  
  19006.  
  19007.  Prototype   int usercreate(ref struct _usr: u);
  19008.  
  19009.  Arguments   u     A reference to a user structure containing the user to
  19010.              be added.
  19011.  
  19012.  Return Val. TRUE if the user was successfully added; FALSE otherwise.
  19013.              (This function may fail if you try to add a user with a name
  19014.              or alias that already exists.)
  19015.  
  19016.  Description The usercreate function adds a user to the user file. The u
  19017.              structure should be completely filled out before the usercre-
  19018.              ate function is called.
  19019.  
  19020.              This function automatically assigns a new lastread pointer to
  19021.              the user before writing it to the user file. (The contents of
  19022.              u.lastread_ptr are ignored.)
  19023.  
  19024.  
  19025.  
  19026.              userfilesize
  19027.  
  19028.  
  19029.  
  19030.  
  19031.  Prototype   long userfilesize();
  19032.  
  19033.  Arguments   None
  19034.  
  19035.  Return Val. The size of the user file, measured in user records.
  19036.  
  19037.  Description The userfilesize returns the number of records (both deleted
  19038.              and non-deleted) that are present in the user file.
  19039.  
  19040.  
  19041.  
  19042.              userfindclose
  19043.  
  19044.  
  19045.  
  19046.  
  19047.  Prototype   void userfindclose();
  19048.  
  19049.  Arguments   None
  19050.  
  19051.  
  19052.  
  19053.              15. MEX Library Reference                                 345
  19054.  
  19055.  Return Val. None
  19056.  
  19057.  Description The userfindclose function releases the resource associated
  19058.              with the most recent call to userfindopen.
  19059.  
  19060.  
  19061.  
  19062.              userfindnext
  19063.  
  19064.  
  19065.  
  19066.  
  19067.  Prototype   int userfindnext(ref struct _usr: u);
  19068.  
  19069.  Arguments   u     A reference to a user structure. This should be a
  19070.              structure returned by a previous call to userfindopen, user-
  19071.              findnext or userfindprev. Upon exit, it is updated with a
  19072.              copy of the new user record.
  19073.  
  19074.  Return Val. TRUE if the following user record was found; FALSE otherwise.
  19075.  
  19076.  Description The userfindnext function finds the next record in the user
  19077.              file and returns it in the u structure.
  19078.  
  19079.  
  19080.  
  19081.              userfindopen
  19082.  
  19083.  
  19084.  
  19085.  
  19086.  Prototype   int userfindopen(string: name, string: alias, ref struct
  19087.              _usr: u);
  19088.  
  19089.  Arguments   name  The name of a user to search for within the user file.
  19090.              If name is the null string (""), the name field in the user
  19091.              record is not compared.
  19092.  
  19093.              alias The alias of a user to search for within the user file.
  19094.              If alias is the null string (""), the alias field in the user
  19095.              record is not compared.
  19096.  
  19097.              u     A reference to a user structure. Upon return, this will
  19098.              be updated with information about the found user record.
  19099.  
  19100.  Return Val. TRUE if the user record was found; FALSE otherwise.
  19101.  
  19102.  Description The userfindopen function is used to initiate a search of the
  19103.              user file. Specifying a name for either name and/or alias in-
  19104.              structs Maximus to look for that specific name or alias
  19105.              within the user file.
  19106.  
  19107.  
  19108.  
  19109.              15. MEX Library Reference                                 346
  19110.  
  19111.              If both name and alias are the null string (""), Maximus will
  19112.              return the first user in the user file.
  19113.  
  19114.              After finding the first record, the userfindnext and user-
  19115.              findprev functions can be used to find the preceding and fol-
  19116.              lowing user records, thereby allowing the entire user file to
  19117.              be searched.
  19118.  
  19119.  
  19120.  
  19121.              userfindprev
  19122.  
  19123.  
  19124.  
  19125.  
  19126.  Prototype   int userfindprev(ref struct _usr: u);
  19127.  
  19128.  Arguments   u     A reference to a user structure. This should be a
  19129.              structure returned by a previous call to userfindopen, user-
  19130.              findnext or userfindprev. Upon exit, it is updated with a
  19131.              copy of the new user record.
  19132.  
  19133.  Return Val. TRUE if the preceding user record was found; FALSE otherwise.
  19134.  
  19135.  Description The userfindprev function finds the previous record in the
  19136.              user file and returns it in the u structure.
  19137.  
  19138.  
  19139.  
  19140.              userfindseek
  19141.  
  19142.  
  19143.  
  19144.  
  19145.  Prototype   int userfindseek(long: rec, ref struct _usr: u);
  19146.  
  19147.  Arguments   rec   The record number to be read from the user file
  19148.  
  19149.              u     A reference to a user record. Upon return, this struc-
  19150.              ture is updated with a copy of the found user record.
  19151.  
  19152.  Return Val. TRUE if the user record was successfully retrieved; FALSE
  19153.              otherwise.
  19154.  
  19155.  Description The userfindseek function seeks directly to the specified
  19156.              user record. userfindopen need not be called prior to using
  19157.              userfindseek.
  19158.  
  19159.              To find the following or preceding user records to the record
  19160.              returned by this function, the userfindopen function must be
  19161.              used (with the u.name and u.alias fields set appropriately)
  19162.              to find this record, and then userfindnext or userfindprev
  19163.              can be used to locate subsequent records.
  19164.  
  19165.  
  19166.  
  19167.              15. MEX Library Reference                                 347
  19168.  
  19169.  
  19170.              userremove
  19171.  
  19172.  
  19173.  
  19174.  
  19175.  Prototype   int userremove(ref struct _usr: u);
  19176.  
  19177.  Arguments   u     A reference to a user record. This user record is to be
  19178.              removed from the user file.
  19179.  
  19180.  Return Val. TRUE if the record was successfully removed; FALSE otherwise.
  19181.  
  19182.  Description This function deletes the user contained in the user record
  19183.              specified by u.
  19184.  
  19185.  
  19186.  
  19187.              userupdate
  19188.  
  19189.  
  19190.  
  19191.  
  19192.  Prototype   int userupdate(ref struct _usr: u, string: origname, string:
  19193.              origalias);
  19194.  
  19195.  Arguments   u     A reference to a user record. The user specified by the
  19196.              origname and origalias fields will have its user record over-
  19197.              written by the record specified by u.
  19198.  
  19199.              origname  The original name of the record to be updated.
  19200.  
  19201.              origalias The original alias of the record to be updated.
  19202.  
  19203.  Return Val. TRUE if the record was successfully updated; FALSE otherwise.
  19204.  
  19205.  Description The userupdate function is used to update an existing record
  19206.              within the user file. The origname and origalias strings are
  19207.              used as keys for locating the original user record. If the
  19208.              user's name or alias has been changed in the update, the
  19209.              origname and origalias fields must reflect the user's origi-
  19210.              nal name and alias, as it was originally read from the user
  19211.              file.
  19212.  
  19213.  
  19214.  
  19215.              vidsync
  19216.  
  19217.  
  19218.  
  19219.  
  19220.  Prototype   void vidsync();
  19221.  
  19222.  
  19223.  
  19224.              15. MEX Library Reference                                 348
  19225.  
  19226.  Arguments   None
  19227.  
  19228.  Return Val. None
  19229.  
  19230.  Description The vidsync function synchronizes screen output with the lo-
  19231.              cal video buffer.
  19232.  
  19233.              vidsync is only needed when the id.instant_video variable is
  19234.              set to 0. If id.instant_video is set to 1, Maximus will han-
  19235.              dle synchronization automatically.
  19236.  
  19237.              The automatic video synchronization can be disabled since up-
  19238.              dating the screen can be a slow process. It is often more ef-
  19239.              ficient to disable screen updates, perform a number of func-
  19240.              tions which modify the screen buffer, and to then call vid-
  19241.              sync when all of the screen updates are complete.
  19242.  
  19243.              Note that many of the internal MEX functions that require in-
  19244.              put (such as input_str and related functions) will automati-
  19245.              cally update the screen regardless of the id.instant_video
  19246.              setting.
  19247.  
  19248.  
  19249.  
  19250.              write
  19251.  
  19252.  
  19253.  
  19254.  
  19255.  Prototype   int write(int: fd, ref string: s, int: len);
  19256.  
  19257.  Arguments   fd    A file descriptor, as returned by the open function.
  19258.  
  19259.              s     A reference to a string. This string should contain the
  19260.              bytes to be written to the file.
  19261.  
  19262.              len   The number of bytes to be written to the file.
  19263.  
  19264.  Return Val. If the return value is the same as len, the write was com-
  19265.              pletely successful.
  19266.  
  19267.              If the return value is less than len, only a portion of the
  19268.              requested number of bytes could be written. The disk is
  19269.              probably full, or some other form of disk error occurred.
  19270.  
  19271.  Description The write function writes a block of bytes to the specified
  19272.              file handle. This function writes blocks of bytes at a time
  19273.              with no consideration for "lines" in the destination file. To
  19274.              write a file a line at a time, see the writeln function.
  19275.  
  19276.  
  19277.  
  19278.              15. MEX Library Reference                                 349
  19279.  
  19280.  
  19281.              writeln
  19282.  
  19283.  
  19284.  
  19285.  
  19286.  Prototype   int writeln(int: fd, string: s);
  19287.  
  19288.  Arguments   fd    A file descriptor, as returned by the open function.
  19289.  
  19290.              s     The string to be written to the file.
  19291.  
  19292.  Return Val. If the return value is equal to strlen(s), the entire line
  19293.              was written to the file.
  19294.  
  19295.              If the return value is less than strlen(s), only part of the
  19296.              string could be written. The disk is probably full, or else
  19297.              some other disk error occurred.
  19298.  
  19299.  Description The writeln function writes an entire line to the specified
  19300.              file handle. Maximus will automatically append a newline to
  19301.              the end of the line.
  19302.  
  19303.  
  19304.  
  19305.              xfertime
  19306.  
  19307.  
  19308.  
  19309.  
  19310.  Prototype   long xfertime(int: protocol, long: bytes);
  19311.  
  19312.  Arguments   protocol  An index specifying the protocol to use for the
  19313.              purposes of time calculation. This can be usr.def_proto or
  19314.              one of the PROTOCOL_* constants from max.mh.
  19315.  
  19316.              bytes The size of the file whose transfer time is to be esti-
  19317.              mated.
  19318.  
  19319.  Return Val. The estimated number of seconds that will be required to
  19320.              transfer the file.
  19321.  
  19322.  Description The xfertime function is used to estimate the period of time
  19323.              that will be required to download a file of a specific size.
  19324.              The protocol parameter is used to calculate variations in the
  19325.              transfer time based on the efficiency of the various proto-
  19326.              cols.
  19327.  
  19328.  
  19329.  
  19330.  
  19331.  
  19332.  
  19333.  
  19334.  
  19335.                                                  16. MEX Language Reference
  19336.  
  19337.  
  19338.              16.1. Operator Precedence
  19339.  
  19340.              The following operator precedence is used in MEX expressions.
  19341.              Table 16.1 lists the operators in order from low to high
  19342.              precedence:
  19343.  
  19344.              Table 16.1 MEX Operator Precedence
  19345.  
  19346.               Operator       Associativity
  19347.  
  19348.               :=             right to left
  19349.               and  or        left to right
  19350.               =  <>          left to right
  19351.               <=  <  >=  >   left to right
  19352.               shl  shr       left to right
  19353.               &  |           left to right
  19354.               +  -           left to right
  19355.               *  /  %        left to right
  19356.               [ ] ( ) .      left to right
  19357.  
  19358.  
  19359.  
  19360.  
  19361.              16.2. Language Grammar
  19362.  
  19363.              This section contains an Extended Backus-Naur Form definition
  19364.              of the MEX grammar:
  19365.  
  19366.              program             <-   top_list
  19367.  
  19368.              top_list            <-     | top_list func_or_decl
  19369.  
  19370.              func_or_decl        <-   function | declaration
  19371.  
  19372.              function            <-   typedefn id ( arg_list )
  19373.                                       trailing_part
  19374.  
  19375.              trailing_part       <-   function_block | ;
  19376.  
  19377.              function_block      <-   { declarator_list statement_list }
  19378.  
  19379.              arg_list            <-     | ... | argument , arg_list
  19380.                                  <-   argument
  19381.  
  19382.              argument            <-   opt_ref typename id
  19383.  
  19384.              opt_ref             <-     | ref
  19385.  
  19386.  
  19387.  
  19388.              16. MEX Language Reference                                352
  19389.  
  19390.  
  19391.              block               <-   { declarator_list statement_list }
  19392.  
  19393.              declarator_list     <-     | declarator_list declaration
  19394.  
  19395.              declaration         <-   typename id_list ;
  19396.                                  <-   struct id { declarator_list } ;
  19397.  
  19398.              typename            <-   typedefn :
  19399.  
  19400.              typedefn            <-   char | int | long | signed char
  19401.                                  <-   signed int
  19402.                                  <-   signed long | unsigned char
  19403.                                  <-   unsigned int
  19404.                                  <-   unsigned long | void | string
  19405.                                  <-   array [ range ] of typedefn
  19406.                                  <-   struct id
  19407.  
  19408.              range               <-   <constant_int> .. <constant_int>
  19409.                                  <-   <constant_int> ..
  19410.  
  19411.              id_list             <-   id_list , id | id
  19412.  
  19413.              statement_list      <-     | statement_list statement
  19414.  
  19415.              opt_statement       <-     | statement
  19416.  
  19417.              statement           <-   ; | block | expr ;
  19418.                                  <-   if paren_expr statement else_part
  19419.                                  <-   goto id ;
  19420.                                  <-   id : statement
  19421.                                  <-   while paren_expr statement |
  19422.                                  <-   do statement while paren_expr ;
  19423.                                  <-   for ( expr ; opt_expr ; opt_expr )
  19424.              statement
  19425.                                  <-   return opt_expr ;
  19426.  
  19427.              else_part           <-     | else statement
  19428.  
  19429.              function_call       <-   id ( expr_list )
  19430.  
  19431.              expr_list           <-     | expr | expr , expr_list
  19432.  
  19433.              primary             <-   paren_expr | ( typedefn ) primary |
  19434.                                  <-   sizeof ( typedefn ) | function_call
  19435.                                  <-   literal | ident
  19436.  
  19437.              opt_expr            <-     | expr
  19438.  
  19439.              paren_expr          <-   ( expr )
  19440.  
  19441.              expr                <-   expr * expr | expr / expr
  19442.                                  <-   expr % expr
  19443.  
  19444.  
  19445.  
  19446.              16. MEX Language Reference                                353
  19447.  
  19448.                                  <-   expr + expr | expr - expr
  19449.                                  <-   expr <= expr
  19450.                                  <-   expr < expr | expr shr expr
  19451.                                  <-   expr shl expr
  19452.                                  <-   expr & expr | expr | expr
  19453.                                  <-   expr and expr
  19454.                                  <-   expr or expr | expr = expr
  19455.                                  <-   expr <> expr
  19456.                                  <-   expr >= expr | expr > expr
  19457.                                  <-   - primary
  19458.                                  <-   primary | ident := expr
  19459.  
  19460.              literal             <-   <constant_char> | <constant_int>
  19461.                                  <-   <constant_long> | const_string
  19462.  
  19463.              const_string        <-   <constant_string> | const_string
  19464.                                  <-   <constant_string>
  19465.  
  19466.              ident               <-   <identifier> | ident [ expr ]
  19467.                                  <-   ident . id
  19468.  
  19469.              id                  <-   <identifier>
  19470.  
  19471.  
  19472.  
  19473.  
  19474.  
  19475.  
  19476.  
  19477.  
  19478.                                                17. MECCA Language Reference
  19479.  
  19480.              This chapter is a guide to the MECCA language.  For informa-
  19481.              tion on the MECCA compiler itself, please see section 8.8.
  19482.  
  19483.  
  19484.              17.1. Usage Guide
  19485.  
  19486.              The MECCA language gives the SysOp a large amount of flexi-
  19487.              bility when designing display screens. MECCA can be use to
  19488.              embed personalized information about the user in text
  19489.              screens, change the text color, run external programs, col-
  19490.              lect answers to a questionnaire, and perform a variety of
  19491.              other functions.
  19492.  
  19493.              The input file for the MECCA compiler normally has a .mec ex-
  19494.              tension and consists of plain ASCII text. The file can also
  19495.              contain special MECCA tokens which are parsed and translated
  19496.              by the MECCA compiler.
  19497.  
  19498.              In MECCA, a token is delimited by a set of square brackets
  19499.              ("[" and "]"). Anything outside of square brackets is treated
  19500.              as text and is displayed to the user as-is. Different types
  19501.              of tokens can be inserted in a MECCA file to achieve differ-
  19502.              ent purposes. For example, the following line of text:
  19503.  
  19504.                 This is your [usercall] call to the system.
  19505.  
  19506.              might be displayed by Maximus as follows, after being com-
  19507.              piled with MECCA:
  19508.  
  19509.                 This is your 14th call to the system.
  19510.  
  19511.              Other tokens can be used to display the user's name, show in-
  19512.              formation about the current node, and perform conditional ac-
  19513.              tions.
  19514.  
  19515.              The MECCA compiler only processes tokens that are contained
  19516.              inside of square brackets. (To include a left square bracket
  19517.              in the output, simply insert two left brackets instead of
  19518.              one. Only the left square bracket needs to be doubled.)
  19519.  
  19520.              For example, to display the following line to a user:
  19521.  
  19522.                 Want to check for your mail [Y,n]?
  19523.  
  19524.              Enter this inside a .mec file:
  19525.  
  19526.                 Want to check for your mail [[Y,n]?
  19527.  
  19528.  
  19529.  
  19530.              17. MECCA Language Reference                              356
  19531.  
  19532.              When using MECCA tokens, also keep these points in mind:
  19533.  
  19534.              *  Tokens are not case-sensitive. That means that the follow-
  19535.                 ing tokens are equivalent in all respects:
  19536.  
  19537.                 [user]
  19538.                 [USER]
  19539.                 [UsEr]
  19540.  
  19541.              *  Spaces are ignored. Inside MECCA tokens, any spaces, tabs
  19542.                 or newlines will have no effect. This means that the fol-
  19543.                 lowing tokens are equivalent in all respects:
  19544.  
  19545.                 [  user  ]
  19546.                 [    user]
  19547.                 [user    ]
  19548.  
  19549.              *  More than one token can be inserted inside a set of square
  19550.                 brackets, as long as tokens are separated from each other
  19551.                 using spaces. For example, this line:
  19552.  
  19553.                 [lightblue][blink][user]
  19554.  
  19555.                 can also be written as follows:
  19556.  
  19557.                 [lightblue blink user]
  19558.  
  19559.              MECCA also allows you to place ASCII codes into the compiled
  19560.              .bbs file. To insert a specific ASCII code, simply enclose
  19561.              the ASCII code number inside a pair of square brackets. For
  19562.              example, the token [123] will be compiled to ASCII code 123
  19563.              in the output file.
  19564.  
  19565.              For conditional testing and flow control, MECCA also allows
  19566.              you to define your own labels. When used with the [goto] to-
  19567.              ken, labels allow your MECCA file to conditionally display
  19568.              parts of the file, based on user input or other various other
  19569.              conditions.
  19570.  
  19571.              A label definition looks similar to an ordinary token, except
  19572.              that the label name is preceded by a slash ("/"). The label
  19573.              name must start with a letter, and it must contain only let-
  19574.              ters, numbers, and underscores. The label name must also be
  19575.              unique, and it cannot use the same name as any existing MECCA
  19576.              token.
  19577.  
  19578.              A sample label definition looks like this:
  19579.  
  19580.                 [/mylabel]
  19581.  
  19582.              When referring to a label as part of a [goto] token, you must
  19583.              omit the preceding slash. (The "/" instructs MECCA to mark
  19584.  
  19585.  
  19586.  
  19587.              17. MECCA Language Reference                              357
  19588.  
  19589.              the file location where the label is placed and use that
  19590.              point as the target for future [goto] tokens.
  19591.  
  19592.              Example #1. This MECCA file displays a prompt to the user and
  19593.              requests a yes or no response. If the user answers "Y," Maxi-
  19594.              mus displays c:\max\misc\games.bbs and asks the question
  19595.              again. Otherwise, Maximus quits the current file. (These
  19596.              MECCA tokens are all described in the following sections, so
  19597.              concentrate on the [goto] and the label definitions for now.)
  19598.  
  19599.                 [/askgames]Want to play more games? [[Y,n]? [menu]YN
  19600.                 [choice]Y[link]C:\Max\Misc\Games
  19601.                 [choice]Y[goto askgames]
  19602.                 [choice]N[quit]
  19603.  
  19604.              Example #2. This code demonstrates a forward-referenced la-
  19605.              bel. The label is actually defined after the [goto] token
  19606.              uses it:
  19607.  
  19608.                 Want a "Zippy the Pinhead" quote? [[y,n]? [menu]YN
  19609.                 [choice]Y[goto zippy]
  19610.                 [choice]N[quit]
  19611.                 [/zippy]
  19612.                 Okay, here's the quote!
  19613.                 [quote quit]
  19614.  
  19615.              For more examples, look at some of the *.mec files in the
  19616.              \max\hlp and \max\misc directories.
  19617.  
  19618.  
  19619.              17.2. Color Token Listing
  19620.  
  19621.              MECCA allows you to use up to 128 different color combina-
  19622.              tions for displaying text. To display text in a different
  19623.              color, simply enclose the name of the color in square brack-
  19624.              ets. For example, [yellow] displays the following text in
  19625.              yellow. (A complete list of permissible colors is given later
  19626.              in this section.)
  19627.  
  19628.              To display text on a colored background, use a token of the
  19629.              form "fore on back"; foreground is the name of the foreground
  19630.              color and background is the name of the background color.
  19631.  
  19632.              For example, to display light green text on a blue back-
  19633.              ground, enter this:
  19634.  
  19635.                 [lightgreen on blue]
  19636.  
  19637.        Note! Only the first eight normal colors (see Table 17.1 below) can
  19638.              be used for the background color. The colors beginning with
  19639.              "light," "dark," "white" and "yellow") can only be used as
  19640.              foreground colors.
  19641.  
  19642.  
  19643.  
  19644.              17. MECCA Language Reference                              358
  19645.  
  19646.              MECCA also supports blinking text. To make text blink, simply
  19647.              insert the [blink] token after the color token. Text that
  19648.              follows this token will blink. (A color token always resets a
  19649.              previous [blink] token, so if you place the [blink] token im-
  19650.              mediately before a color token, the [blink] token will have
  19651.              no effect.)
  19652.  
  19653.              For example, the following line displays blinking green text:
  19654.  
  19655.                 [green blink]Hello, world!
  19656.  
  19657.              However, this line displays non-blinking text:
  19658.  
  19659.                 [blink green]Hello, world!
  19660.  
  19661.              If the user has disabled ANSI or AVATAR graphics support,
  19662.              Maximus will automatically strip out the color and cursor-
  19663.              movement codes before transmitting the screen to the user.
  19664.              Consequently, the same colorized screen can be shown to users
  19665.              with either TTY or ANSI/AVATAR terminals.
  19666.  
  19667.              Table 17.1 lists the colors supported by MECCA:
  19668.  
  19669.              Table 17.1 MECCA Colors
  19670.  
  19671.               Foreground and Background   Foreground only
  19672.  
  19673.               [black]                     [darkgray]
  19674.               [blue]                      [lightblue]
  19675.               [green]                     [lightgreen]
  19676.               [cyan]                      [lightcyan]
  19677.               [red]                       [lightred]
  19678.               [magenta]                   [lightmagenta]
  19679.               [brown]                     [yellow]
  19680.               [gray]                      [white]
  19681.  
  19682.  
  19683.              Other tokens relating to colors are:
  19684.  
  19685.              [BG <c>]
  19686.  
  19687.                 This token is a MECCA directive that modifies the current
  19688.                 background color without changing the foreground color. The
  19689.                 new background color is set to <c>.
  19690.  
  19691.                 For example, this code:
  19692.  
  19693.                 [red on blue]Hello, [BG green]user
  19694.  
  19695.                 displays the text "Hello," in red on blue, while it dis-
  19696.                 plays "user" in red on green.
  19697.  
  19698.  
  19699.  
  19700.              17. MECCA Language Reference                              359
  19701.  
  19702.              [blink] - ^v^b
  19703.  
  19704.                 Any text that follows this token will blink. The blinking
  19705.                 attribute is reset when Maximus encounters a color token.
  19706.  
  19707.               [bright]
  19708.  
  19709.                 This token is a MECCA directive that sets the intensity bit
  19710.                 of the current color. If the current foreground color is on
  19711.                 the left hand side of Table 17.1, MECCA sets the new color
  19712.                 to the equivalent color on the right hand side of the ta-
  19713.                 ble.
  19714.  
  19715.                 For example, the following code:
  19716.  
  19717.                 [red]Is it not a [lightred]BEAUTIFUL DAY?
  19718.  
  19719.                 can be replaced with this simpler form:
  19720.  
  19721.                 [red]Is it not a [bright]BEAUTIFUL DAY?
  19722.  
  19723.              [dim]
  19724.  
  19725.                 This token is a MECCA directive that disables the intensity
  19726.                 bit for the current color. Similar to the [bright] token,
  19727.                 it translates colors from the right hand side of the color
  19728.                 table to the equivalent color on the left hand side of the
  19729.                 table.
  19730.  
  19731.                 For example, this code:
  19732.  
  19733.                 [lightgreen]H[dim]e[bright]l[dim]l[bright]o[dim]!
  19734.  
  19735.                 displays the word "Hello!", with each character alternating
  19736.                 between normal green and light green.
  19737.  
  19738.              [FG <c>]
  19739.  
  19740.                 This token is a MECCA directive that modifies the current
  19741.                 foreground color without changing the background color. The
  19742.                 new foreground color is set to <c>.
  19743.  
  19744.                 For example:
  19745.  
  19746.                 [lightred on blue]Hi, [FG yellow]Mr. Smith...
  19747.  
  19748.                 The above line displays the text "Hi," in lightred on blue,
  19749.                 and it displays the phrase "Mr. Smith" in yellow on blue.
  19750.  
  19751.               [load]
  19752.  
  19753.                 This token is a MECCA directive which restores the color
  19754.                 that was previously saved using the [save] token.
  19755.  
  19756.  
  19757.  
  19758.              17. MECCA Language Reference                              360
  19759.  
  19760.                 These two tokens are useful when creating screens with
  19761.                 backgrounds, since repeatedly typing two different colors
  19762.                 can get verbose. (To alternate between two colors, you can
  19763.                 save the first color by using [save], and after inserting
  19764.                 the command to change to another color, you can restore the
  19765.                 first color by inserting a [load] token.)
  19766.  
  19767.                 For example:
  19768.  
  19769.                 [yellow on blue save]This is yellow on blue.[cleol]
  19770.                 [lightred on green]This is lightred on green.[cleol]
  19771.                 [load]This text is also yellow on blue.[cleol]
  19772.  
  19773.              [on]
  19774.  
  19775.                 This is a MECCA directive which tells MECCA to interpret
  19776.                 the next token as a background color. See the introduction
  19777.                 at the beginning of this section for more information.
  19778.  
  19779.              [save]
  19780.  
  19781.                 This keyword is a MECCA directive that tells MECCA to save
  19782.                 the current color and store it for retrieval by the [load]
  19783.                 token.
  19784.  
  19785.              [steady]
  19786.  
  19787.                 This keyword is a MECCA directive that disables a previous
  19788.                 [blink] token.
  19789.  
  19790.                 For example:
  19791.  
  19792.                 [yellow]This does not blink. [blink]This does.
  19793.                 [steady]However, this text is non-blinking.
  19794.  
  19795.  
  19796.              17.3. Cursor Control and Video Tokens
  19797.  
  19798.              This section describes video and terminal control commands
  19799.              that can be used to move the cursor and manipulate the
  19800.              caller's screen.
  19801.  
  19802.               [bell] - ^g
  19803.  
  19804.                 This causes a beep (ASCII 07) to be generated on the user's
  19805.                 terminal.
  19806.  
  19807.              [bs] - ^h
  19808.  
  19809.                 This causes a backspace (ASCII 08) to be generated on the
  19810.                 user's terminal. This token moves the cursor left by one
  19811.                 column.
  19812.  
  19813.  
  19814.  
  19815.              17. MECCA Language Reference                              361
  19816.  
  19817.              [cleol] - ^v^g
  19818.  
  19819.                 This instructs Maximus to send a clear to end of line com-
  19820.                 mand. If the current background color is non-black, the
  19821.                 rest of the line is set to that color.
  19822.  
  19823.              [cleos] - ^v^o
  19824.  
  19825.                 This instructs Maximus to clear out part of the screen,
  19826.                 from the current cursor position to the end of the screen.
  19827.                 The cleared screen is set to the current color, and the
  19828.                 cursor position is not changed. This is not a true AVATAR
  19829.                 sequence, but Maximus will automatically generate the ap-
  19830.                 propriate commands to clear the screen.
  19831.  
  19832.               [cls] - ^l
  19833.  
  19834.                 This clears the user's screen and sets the current color to
  19835.                 cyan.
  19836.  
  19837.              [cr] - ^m
  19838.  
  19839.                 This sends a carriage return to the user.
  19840.  
  19841.              [down] - ^v^d
  19842.  
  19843.                 This tells Maximus to move the cursor by down one row.
  19844.  
  19845.              [left] - ^v^e
  19846.  
  19847.                 This moves the cursor one column to the left.
  19848.  
  19849.              [lf] - ^j
  19850.  
  19851.                 This sends a linefeed to the user.
  19852.  
  19853.              [locate <r> <c>] - ^v^h<r><c>
  19854.  
  19855.                 This command moves the cursor to the <r>th row and the
  19856.                 <c>th column of the screen. (The top left corner of the
  19857.                 screen is row 1, column 1.)
  19858.  
  19859.              [tab] - ^i
  19860.  
  19861.                 This command sends a tab character to the user.
  19862.  
  19863.              [right] - ^v^f
  19864.  
  19865.                 This moves the cursor one column to the right.
  19866.  
  19867.  
  19868.  
  19869.              17. MECCA Language Reference                              362
  19870.  
  19871.               [sysopbell] - ^w^g
  19872.  
  19873.                 This token sounds a beep on the local console. The beep is
  19874.                 not transmitted to the on-line user.
  19875.  
  19876.               [up] - ^v^c
  19877.  
  19878.                 This moves the cursor up by one row.
  19879.  
  19880.  
  19881.              17.4. Informational Tokens
  19882.  
  19883.              Maximus includes a large number of tokens that display se-
  19884.              lected information about the user and about the system in
  19885.              general. Maximus supports the following informational tokens:
  19886.  
  19887.               [alist_file] - ^rlF
  19888.  
  19889.                 Display the file area menu. If a Uses FileAreas file is de-
  19890.                 fined in the system control file, this token will display
  19891.                 it. Otherwise, Maximus will automatically build an area
  19892.                 list and display it to the user.
  19893.  
  19894.              [alist_msg] - ^rlM
  19895.  
  19896.                 Display the message area menu. If a Uses MsgAreas file is
  19897.                 defined, this token will display it. Otherwise, Maximus
  19898.                 will automatically build an area list and display it to the
  19899.                 user.
  19900.  
  19901.              [city] - ^f^c
  19902.  
  19903.                 Display the user's city.
  19904.  
  19905.              [date] - ^f^d
  19906.  
  19907.                 Display the current date in the "dd mmm yy" format.
  19908.  
  19909.              [dl] - ^f^x
  19910.  
  19911.                 Display the user's total number of kilobytes downloaded,
  19912.                 including today's downloads.
  19913.  
  19914.              [expiry_date] - ^wyD
  19915.  
  19916.                 Display the user's current expiration date, or "None" if
  19917.                 the user has no expiration date.
  19918.  
  19919.              [expiry_time] - ^wyT
  19920.  
  19921.                 This displays the time left in the current user's subscrip-
  19922.                 tion. If the user has time remaining, this token displays
  19923.                 "x minutes," where x is the number of minutes remaining in
  19924.  
  19925.  
  19926.  
  19927.              17. MECCA Language Reference                              363
  19928.  
  19929.                 the user's subscription. If the user has no time subscrip-
  19930.                 tion, this token displays "None."
  19931.  
  19932.              [file_carea] - ^w^fA
  19933.  
  19934.                 Display the name of the current file area.
  19935.  
  19936.              [file_cname] - ^w^fN
  19937.  
  19938.                 Display the description for the current file area.
  19939.  
  19940.               [file_darea] - ^w^fD
  19941.  
  19942.                 Display the name of the current file area division.
  19943.  
  19944.               [file_sarea] - ^w^fd
  19945.  
  19946.                 Display the name of the current file area (without the di-
  19947.                 vision prefix).
  19948.  
  19949.               [fname]
  19950.              [first] - ^f^f
  19951.  
  19952.                 Display the user's first name.
  19953.  
  19954.              [lastcall] - ^w^a
  19955.  
  19956.                 Display the date of the user's last call.
  19957.  
  19958.              [lastuser] - ^w^k
  19959.  
  19960.                 Display the name of the last user to call the current node.
  19961.                 This information is read from the bbstat##.bbs file from
  19962.                 the Maximus system directory.
  19963.  
  19964.               [length] - ^f^l
  19965.  
  19966.                 Display the duration of this user's call, in minutes.
  19967.  
  19968.              [minutes] - ^f^k
  19969.  
  19970.                 Display the number of minutes for which the user has been
  19971.                 on-line during the last 24 hours.
  19972.  
  19973.              [msg_carea] - ^w^mA
  19974.  
  19975.                 Display the name of the current message area.
  19976.  
  19977.               [msg_cmsg] - ^w^mL
  19978.  
  19979.                 Display the current message number.
  19980.  
  19981.  
  19982.  
  19983.              17. MECCA Language Reference                              364
  19984.  
  19985.               [msg_cname] - ^w^mN
  19986.  
  19987.                 Display the description for the current message area.
  19988.  
  19989.               [msg_darea] - ^w^mD
  19990.  
  19991.                 Display the name of the current message area division.
  19992.  
  19993.               [msg_hmsg] - ^w^mH
  19994.  
  19995.                 Display the highest message number in the current area.
  19996.  
  19997.               [msg_nummsg] - ^w^m#
  19998.  
  19999.                 Display the number of messages in the current area.
  20000.  
  20001.              [msg_sarea] - ^w^md
  20002.  
  20003.                 Display the current message area (without the division pre-
  20004.                 fix).
  20005.  
  20006.               [netbalance] - ^w^nB
  20007.  
  20008.                 Display the current user's matrix balance (credit minus
  20009.                 debit) in cents.
  20010.  
  20011.              [netcredit] - ^w^nC
  20012.  
  20013.                 Display the current user's matrix credit in cents.
  20014.  
  20015.              [netdebit] - ^w^nD
  20016.  
  20017.                 Display the current user's matrix debit in cents.
  20018.  
  20019.              [netdl] - ^f^r
  20020.  
  20021.                 This displays the user's net downloads for today (today's
  20022.                 downloads minus today's uploads).
  20023.  
  20024.              [node_num] - ^wjN
  20025.  
  20026.                 Display the current node number.
  20027.  
  20028.              [phone] - ^wP
  20029.  
  20030.                 Display the user's phone number.
  20031.  
  20032.              [ratio] - ^f^y
  20033.  
  20034.                 Display the current user's download ratio, in the format of
  20035.                 uploads:downloads.
  20036.  
  20037.  
  20038.  
  20039.              17. MECCA Language Reference                              365
  20040.  
  20041.              [realname] - ^wR
  20042.  
  20043.                 Display the user's real name (if applicable).
  20044.  
  20045.              [remain] - ^f^o
  20046.  
  20047.                 Display the number of minutes that the user has left for
  20048.                 the current call.
  20049.  
  20050.              [response] - ^w^e
  20051.  
  20052.                 Display the last line entered by the user for a [readln]
  20053.                 response. This token even works across files ---if one file
  20054.                 contain a [readln] token, the [response] token can be in-
  20055.                 serted in a separate file to display the result. See also
  20056.                 [ifentered].
  20057.  
  20058.              [syscall] - ^f^q
  20059.  
  20060.                 Display the total number of calls that the current node has
  20061.                 received (as an ordinal number).
  20062.  
  20063.               [sys_name] - ^r^c
  20064.  
  20065.                 Display the system name.
  20066.  
  20067.              [sysop_name] - ^r^d
  20068.  
  20069.                 Display the SysOp's full name.
  20070.  
  20071.               [time] - ^f^t
  20072.  
  20073.                 Display the current time in the format "hh:mm:ss".
  20074.  
  20075.              [timeoff] - ^f^p
  20076.  
  20077.                 Displays the time by which the user must be off the system.
  20078.                 This string includes a newline at the end; unless you want
  20079.                 to have a blank line displayed in your output file, you
  20080.                 should not press <enter> immediately after entering this
  20081.                 token in the MECCA source file.
  20082.  
  20083.              [ul] - ^f^w
  20084.  
  20085.                 Display the count of kilobytes uploaded, including today's
  20086.                 statistics.
  20087.  
  20088.              [user] - ^f^b
  20089.  
  20090.                 Display the user's full name.
  20091.  
  20092.  
  20093.  
  20094.              17. MECCA Language Reference                              366
  20095.  
  20096.              [usercall] - ^f^e
  20097.  
  20098.                 Display the number of times the current user has called
  20099.                 your system (as an ordinal number).
  20100.  
  20101.  
  20102.              17.5. Questionnaire Token Listing
  20103.  
  20104.              The tokens in this section can be used to design on-line
  20105.              questionnaires and to log information to a file. All of the
  20106.              questionnaire tokens are described later in this section, but
  20107.              most questionnaires will follow the general format given be-
  20108.              low:
  20109.  
  20110.              One of the first tokens in a questionnaire file should be the
  20111.              [open] token. This token opens the specified filename for
  20112.              output, and this is where Maximus logs all of the question-
  20113.              naire answers. (This file is human-readable, so you can view
  20114.              the file with a normal text editor.)
  20115.  
  20116.              A [post] token normally follows the [open] token. The [post]
  20117.              writes the user's name, city, and the current date/time to
  20118.              the questionnaire file. (For an anonymous questionnaire, this
  20119.              step can be omitted.)
  20120.  
  20121.              You can then insert the main body of the questionnaire. The
  20122.              [readln] token is used to request input from the user. All of
  20123.              the input lines are written to the questionnaire file that
  20124.              was opened using [open].
  20125.  
  20126.              The [store] can also be used to store the response to a menu
  20127.              displayed by [menu].
  20128.  
  20129.              Finally, you can also use the [write] to write lines directly
  20130.              to the questionnaire file. These lines can include external
  20131.              program translation characters, as described in section 6.5.
  20132.  
  20133.              You can place as many questions in a questionnaire as de-
  20134.              sired. These questionnaire tokens can be placed in any .mec
  20135.              file.
  20136.  
  20137.              The following tokens are related to designing questionnaires:
  20138.  
  20139.              [ansopt] - ^f^v
  20140.  
  20141.                 After this token is encountered, Maximus will not require
  20142.                 an answer for [menu] and [readln] tokens. The user can sim-
  20143.                 ply press <enter> to skip the prompt.
  20144.  
  20145.               [ansreq] - ^f^u
  20146.  
  20147.                 After this token is encountered, Maximus will require an
  20148.                 answer for all [menu] and [readln] tokens.
  20149.  
  20150.  
  20151.  
  20152.              17. MECCA Language Reference                              367
  20153.  
  20154.              [choice]<c> - ^oU<c>
  20155.  
  20156.                 Display the rest of the current line only if the response
  20157.                 to the last [menu] choice is equal to the character <c>.
  20158.  
  20159.              [leave_comment] - ^wK
  20160.  
  20161.                 Place the user in the message editor and allow the user to
  20162.                 write a message to the SysOp. The message is saved in the
  20163.                 area defined by Comment Area in the system control file.
  20164.  
  20165.                 If the message is aborted by the user, or if the message
  20166.                 saved by the user is blank, Maximus will skip the rest of
  20167.                 the line containing the [leave_comment] token.
  20168.  
  20169.                 This construct allow you to determine if the user entered a
  20170.                 message and react accordingly:
  20171.  
  20172.                 Please leave a comment to the SysOp, [fname].
  20173.                 [enter]
  20174.                 [/Do_Comment leave_comment goto Successful]
  20175.  
  20176.                 You did not leave a real message! Try again...
  20177.                 [enter goto Do_Comment]
  20178.  
  20179.                 [/Successful]Thanks for leaving a comment, [fname].
  20180.  
  20181.              [menu]<k> - ^oR<k>
  20182.  
  20183.                 This token prompts the user to press a key. The value en-
  20184.                 tered by the user can be later manipulated using the
  20185.                 [choice] and [store] tokens.
  20186.  
  20187.                 <k> is a list of valid keys that the user can use to re-
  20188.                 spond to the menu. If the [ansopt] token is in effect, the
  20189.                 user can also press <enter> to skip the question.
  20190.  
  20191.                 If the user enters a key which is not in <k>, Maximus dis-
  20192.                 plays an error message and prompts the user to try again.
  20193.                 The characters in <k> can be any character between ASCII 33
  20194.                 and ASCII 126, including letters, numbers and punctuation
  20195.                 marks.
  20196.  
  20197.               [open]<f> - ^oO<f>
  20198.  
  20199.                 This command instructs Maximus to open a questionnaire an-
  20200.                 swer file called <f>. See also [post], [store] and
  20201.                 [readln]. Maximus honors external program translation char-
  20202.                 acters in this filename.
  20203.  
  20204.  
  20205.  
  20206.              17. MECCA Language Reference                              368
  20207.  
  20208.              [post] - ^oP
  20209.  
  20210.                 Write the user's name, city, and the current time/date to
  20211.                 the questionnaire answer file.
  20212.  
  20213.              [readln]<d> - ^oN<d>
  20214.  
  20215.                 Retrieve a line of input from the user, and then write it
  20216.                 to the questionnaire answer file, placing the optional one-
  20217.                 word description <d> beside the user's answer.
  20218.  
  20219.                 By default, the [readln] token allows stacked commands. For
  20220.                 example, if a user entered input that was not used by a
  20221.                 prior prompt, any remaining input in the key input buffer
  20222.                 will be read by the [readln] command. To disable this func-
  20223.                 tionality, include a [clear_stacked] token just before the
  20224.                 [readln] token.
  20225.  
  20226.              [sopen]<f> - ^oo<f>
  20227.  
  20228.                 Open a questionnaire answer file called <f>. This token is
  20229.                 identical to the [open] token.
  20230.  
  20231.               [store]<d> - ^oM<d>
  20232.  
  20233.                 Writes the user's response to the last [menu] token into
  20234.                 the questionnaire answer file, placing the optional one-
  20235.                 word description <d> beside the user's answer.
  20236.  
  20237.              [write]<l> - ^wW<l>
  20238.  
  20239.                 Write the line <l> directly to the questionnaire answer
  20240.                 file, interpreting any external program translation charac-
  20241.                 ters contained within. Please see section 6.5 for more in-
  20242.                 formation.
  20243.  
  20244.  
  20245.              17.6. Privilege Level Controls
  20246.  
  20247.              These tokens allow certain parts of a MECCA file to be dis-
  20248.              played or skipped, depending on the user's current privilege
  20249.              level.
  20250.  
  20251.              [?below], [?equal], [?file], [?line], [?xclude],[above],
  20252.              [ae], [be], [below], [eq], [equal], [ge], [gt], [le], [lt],
  20253.              [ne], [notequal], [unequal]
  20254.  
  20255.                 These keywords are obsolete. These keywords are only sup-
  20256.                 ported for compatibility with previous versions of Maximus.
  20257.  
  20258.  
  20259.  
  20260.              17. MECCA Language Reference                              369
  20261.  
  20262.              [acs <acs-string>]
  20263.              [access <acs-string>] - ^pa<acs-string><space>
  20264.  
  20265.                 Display the rest of the line only if the user's access
  20266.                 level passes the ACS given by <acs-string>. Any type of ACS
  20267.                 test can be included here.
  20268.  
  20269.              [acsfile <acs-string>]
  20270.              [accessfile <acs-string>] - ^pf<acs-string><space>
  20271.  
  20272.                 Display the rest of the file only if the user's access
  20273.                 level passes the ACS given by <acs-string>. Any type of ACS
  20274.                 test can be included here.
  20275.  
  20276.              [priv_abbrev] - ^vpa
  20277.  
  20278.                 Display the user's class level abbreviation. (For example,
  20279.                 this could display "SysOp" or "AsstSysOp," depending on the
  20280.                 definition in the access control file.)
  20281.  
  20282.               [priv_desc] - ^vpd
  20283.  
  20284.                 Display the user's class level description, as defined in
  20285.                 the access control file.
  20286.  
  20287.               [priv_down] - ^wpD
  20288.  
  20289.                 Lower the privilege level of the current user to that of
  20290.                 the next lower user class.
  20291.  
  20292.              [priv_level] - ^vpl
  20293.  
  20294.                 Display the user's numeric privilege level.
  20295.  
  20296.              [priv_up] - ^wpU
  20297.  
  20298.                 Raise the privilege level of the current user to that of
  20299.                 the next higher user class.
  20300.  
  20301.               [setpriv <priv>] - ^ws?
  20302.  
  20303.                 Adjusts the current user's privilege level to a certain
  20304.                 value. <priv> should be the single-character key value as-
  20305.                 sociated with a user class defined in the access control
  20306.                 file.
  20307.  
  20308.  
  20309.              17.7. Lock and Key Control
  20310.  
  20311.              [ifkey]<keys> - ^wkI
  20312.  
  20313.                 If the specified keys are set, the rest of the line is dis-
  20314.                 played. Any number of keys can be specified, but they must
  20315.  
  20316.  
  20317.  
  20318.              17. MECCA Language Reference                              370
  20319.  
  20320.                 be separated from the rest of the line by a space. For ex-
  20321.                 ample:
  20322.  
  20323.                 [ifkey]123a You have keys 1,2, 3 and A.
  20324.  
  20325.              [notkey]<keys> - ^wkN
  20326.  
  20327.                 This token is similar to [ifkey], except that the line is
  20328.                 displayed only if the specified keys are not set.
  20329.  
  20330.                 For example:
  20331.  
  20332.                 [notkey]8b You have neither key 8 nor key b.
  20333.  
  20334.              [keyon]<keys> - ^wkO
  20335.  
  20336.                 This command gives the specified keys to the user. <keys>
  20337.                 must be separated from the rest of the line with a space.
  20338.  
  20339.                 [keyon]6abc User, you now have keys A, B, C and 6.
  20340.  
  20341.              [keyoff]<keys> - ^wkF
  20342.  
  20343.                 This command takes the specified keys away from the user.
  20344.                 <keys> must be separated from the rest of the line with a
  20345.                 space.
  20346.  
  20347.                 This command turns off the specified keys.
  20348.  
  20349.                 [keyoff]fgh User, keys F, G and H have been removed.
  20350.  
  20351.              17.8. Conditional and Flow Control Tokens
  20352.  
  20353.              These tokens allow you to conditionally display different
  20354.              parts of a file, depending on various user attributes and
  20355.              system settings.
  20356.  
  20357.              [b1200] - ^w^b1
  20358.  
  20359.                 Display the rest of the line only if the user is connected
  20360.                 at 1200 bps or above.
  20361.  
  20362.                 Using this construct, you can use the [b1200] token to dis-
  20363.                 play a line only to users who are calling at a speed slower
  20364.                 than 1200 bps:
  20365.  
  20366.                 [b1200 goto FastUser]
  20367.                 You are a 300 baud user!
  20368.                 [goto Done]
  20369.  
  20370.                 [/FastUser]
  20371.                 You are a 1200 bps or above user!
  20372.                 [/Done]
  20373.  
  20374.  
  20375.  
  20376.              17. MECCA Language Reference                              371
  20377.  
  20378.  
  20379.              [b2400] - ^w^b2
  20380.  
  20381.                 Display the rest of the line only if the user is connected
  20382.                 at 2400 bps or above.
  20383.  
  20384.              [b9600] - ^w^b9
  20385.  
  20386.                 Display the rest of the line only if the user is connected
  20387.                 at 9600 bps or above.
  20388.  
  20389.              [col80] - ^w8
  20390.  
  20391.                 Display the rest of the line only if the user's screen is
  20392.                 at least 79 columns wide.
  20393.  
  20394.              [color] - ^oE
  20395.              [colour] - Canadian spelling of above
  20396.  
  20397.                 Display the following text (up to the next [endcolor] to-
  20398.                 ken), only if the user has ANSI or AVATAR graphics. See
  20399.                 also [nocolor].
  20400.  
  20401.              [endcolor] - ^oe
  20402.              [endcolour] - Canadian spelling of above
  20403.  
  20404.                 This token marks the end of a "color-only" display se-
  20405.                 quence. See also [color].
  20406.  
  20407.              [endrip] - ^oI
  20408.  
  20409.                 This token marks the end of a "RIPscrip-only" display. See
  20410.                 also [rip].
  20411.  
  20412.               [expert] - ^wHE
  20413.  
  20414.                 Display the rest of the line only if the user's current
  20415.                 help level is expert.
  20416.  
  20417.              [exit] - ^wE
  20418.  
  20419.                 Exit all display files, including those which were dis-
  20420.                 played using a [link] token. See also [quit].
  20421.  
  20422.               [filenew]<f> - ^wf
  20423.  
  20424.                 Display the rest of the current line if the file <f> is
  20425.                 newer than the user's last log-on date. The file <f> must
  20426.                 be separated from the rest of the line by a space. This
  20427.                 means that a construct such as this can be used to display
  20428.                 a file only if the user has not seen it before:
  20429.  
  20430.  
  20431.  
  20432.              17. MECCA Language Reference                              372
  20433.  
  20434.                 [filenew]c:\max\misc\bulletin.bbs
  20435.                 [display]c:\max\misc\bulletin.bbs
  20436.  
  20437.              [goto <l>] - ^oV
  20438.  
  20439.                 Jump to the label <l> in the current file.
  20440.  
  20441.               [hotkeys] - ^rh
  20442.  
  20443.                 Display the rest of the current line only to those users
  20444.                 who have hotkeys enabled.
  20445.  
  20446.               [ifentered]<s> - ^we<s>
  20447.  
  20448.                 This token compares <s> to the response given by the user
  20449.                 to the last [readln] token. If the two strings are equal,
  20450.                 the rest of the line is displayed. <s> is separated from
  20451.                 the rest of the line by a single space.
  20452.  
  20453.                 For example, given the following code:
  20454.  
  20455.                 What kind of yogurt do you like best? [readln]
  20456.                 [ifentered]peach You are a real peach!
  20457.                 [ifentered]lemon You are what you eat!
  20458.  
  20459.                 If the user enters "peach" at the prompt, Maximus will dis-
  20460.                 play "You are a real peach!" If the user enters "lemon,"
  20461.                 Maximus will display "You are what you eat!" If the user
  20462.                 entered neither string, Maximus would display nothing.
  20463.  
  20464.              [ifexist]<filename> - ^wi<filename>
  20465.  
  20466.                 The rest of the line is displayed only if the file
  20467.                 <filename> exists. The filename must be separated from the
  20468.                 rest of the line by a space.
  20469.  
  20470.              [iffse] - ^w^mE
  20471.  
  20472.                 Display the rest of the line only if the user has enabled
  20473.                 the full-screen editor.
  20474.  
  20475.               [iffsr] - ^w^mR
  20476.  
  20477.                 Display the rest of the line only if the user has the full-
  20478.                 screen reader enabled.
  20479.  
  20480.               [iflang]<l> - ^wB<l>
  20481.  
  20482.                 Display the rest of the line if the user's language is set
  20483.                 to language number <l>. The language number is 0-based, so
  20484.                 a "0" means the first language listed in the language con-
  20485.                 trol file, "1" means the second language, and so on.
  20486.  
  20487.  
  20488.  
  20489.              17. MECCA Language Reference                              373
  20490.  
  20491.              [iftask]<tasknum> - ^wb<tasknum>
  20492.  
  20493.                 Display the rest of the line if the current node is
  20494.                 <tasknum> (in decimal). The task number is separated from
  20495.                 the rest of the line by a space.
  20496.  
  20497.              [iftime <op> <hh>:<mm>]
  20498.  
  20499.                 Display the rest of the line only if the current time of
  20500.                 day matches a specified condition.
  20501.  
  20502.                 <op> specifies the type of comparison operation to perform.
  20503.                 The supported operators are listed below in Table 17.2:
  20504.  
  20505.                 Table 17.2 [iftime] Operations
  20506.  
  20507.                 Operator            Description
  20508.  
  20509.                 EQ or EQUAL         Display the rest of the line only if
  20510.                                     the current time equals hh:mm.
  20511.                 NE or NOTEQUAL      Display the rest of the line only if
  20512.                                     the current time is not equal to hh:mm.
  20513.                 LT or BELOW         Display the rest of the line only if it
  20514.                                     is currently earlier than (and not ex-
  20515.                                     actly) hh:mm.
  20516.                 GT or ABOVE         Display the rest of the line only if it
  20517.                                     is currently later than (and not ex-
  20518.                                     actly) hh:mm.
  20519.                 GE or AE            Display the rest of the line only if it
  20520.                                     is currently later than (or equal to)
  20521.                                     hh:mm.
  20522.                 LE or BE            Display the rest of the line only if it
  20523.                                     is earlier later than (or equal to)
  20524.                                     hh:mm.
  20525.  
  20526.  
  20527.                 <hh> and <mm> tell Maximus which hour and minute to compare
  20528.                 with, specified in 24-hour format.
  20529.  
  20530.                 For example:
  20531.  
  20532.                 [iftime GE 20:00]It is after 8 pm!
  20533.                 [iftime GE 20:00 iftime LE 21:00]Between 8 and 9 pm.
  20534.                 [iftime LT 20:00 iftime NE 12:00]Before 8 & not 12.
  20535.  
  20536.              [incity]<s> - ^wR
  20537.  
  20538.                 Display the rest of the line if the string <s> can be found
  20539.                 in the user's city field. <s> should be separated from the
  20540.                 rest of the line by a single space.
  20541.  
  20542.                 Example:
  20543.  
  20544.  
  20545.  
  20546.              17. MECCA Language Reference                              374
  20547.  
  20548.                 [incity]Toronto Hi, [first]. You are a Torontonian!
  20549.  
  20550.              [islocal] - ^wIL
  20551.  
  20552.                 Display the rest of the line only if the user is logged in
  20553.                 at the local console.
  20554.  
  20555.              [isremote] - ^wIR
  20556.  
  20557.                 Display the rest of the line only if the user is logged in
  20558.                 from remote.
  20559.  
  20560.              [jump] - ^oV
  20561.  
  20562.                 This token is a synonym for [goto].
  20563.  
  20564.              [label <l>]
  20565.  
  20566.                 This token provides an alternate way to define a label. The
  20567.                 sequence "[label <l>]" is identical to "[/<l>]".
  20568.  
  20569.              [maxed] - ^wm
  20570.  
  20571.                 Display the rest of the line only if the user is currently
  20572.                 in the MaxEd editor. This token can be useful when design-
  20573.                 ing a custom menu for the editor.
  20574.  
  20575.               [msg_attr <letter>] - ^w^mB<letter>
  20576.  
  20577.                 This token displays the rest of the line only if the user
  20578.                 has sufficient access rights to create a message with the
  20579.                 specified attribute type.
  20580.  
  20581.                 <letter> must correspond to a character in the msgattr_keys
  20582.                 variable in the system language file. The default keys for
  20583.                 the English language are listed below in Table 17.3:
  20584.  
  20585.                 Table 17.3 [msg_attr] Keys
  20586.  
  20587.                 Key    Attribute
  20588.  
  20589.                 P      Private
  20590.                 C      Crash
  20591.                 R      Received
  20592.                 S      Sent
  20593.                 A      Attach (file)
  20594.                 F      Forward
  20595.                 O      Orphan
  20596.                 K      Kill/Sent
  20597.                 L      Local
  20598.                 H      Hold
  20599.                 X      Xx2 (undefined)
  20600.                 G      File Request
  20601.  
  20602.  
  20603.  
  20604.              17. MECCA Language Reference                              375
  20605.  
  20606.                 !      Receipt Request
  20607.                 $      Return Receipt
  20608.                 T      Trail Request
  20609.                 U      Update Request
  20610.  
  20611.  
  20612.                 For example:
  20613.  
  20614.                 [          ]Key     Action
  20615.                 [          ]======= ==================================
  20616.                 [msg_attr P]P       To toggle the PRIVATE flag
  20617.                 [msg_attr C]C       To toggle crash status
  20618.                 [msg_attr A]A       To attach a file
  20619.                 [msg_attr R]R       To toggle the Received flag
  20620.                 [msg_attr S]S       To toggle the Sent flag
  20621.                 [msg_attr F]F       To toggle the Forward flag
  20622.                 [msg_attr O]O       To toggle the Orphan flag
  20623.                 [msg_attr K]K       To kill the message after packing
  20624.                 [msg_attr H]H       To keep message on hold for pickup
  20625.                 [msg_attr G]G       To request a file
  20626.                 [msg_attr !]!       To request a receipt
  20627.                 [msg_attr $]$       To toggle the receipt flag
  20628.                 [msg_attr T]T       To request a trail
  20629.                 [msg_attr U]U       To place an update request
  20630.                 [          ]<enter> To proceed to the next field
  20631.                 [white enter quit]
  20632.  
  20633.              [msg_conf] - ^w^maC
  20634.  
  20635.                 Display the rest of the line only if the current message
  20636.                 area is a conference area.
  20637.  
  20638.               [msg_echo] - ^w^maE
  20639.  
  20640.                 Display the rest of the line only if the current message
  20641.                 area is an EchoMail area.
  20642.  
  20643.              [msg_fileattach] - ^w^mF
  20644.  
  20645.                 Display the rest of the line only if the user has pending
  20646.                 file attaches in the message area. This token will not de-
  20647.                 tect inbound FTS-0001 style attaches.
  20648.  
  20649.                 For example:
  20650.  
  20651.                 [msg_fileattach][yellow blink]You have files attached!
  20652.  
  20653.               [msg_local] - ^w^maL
  20654.  
  20655.                 Display the rest of the line only if the current message
  20656.                 area is a local area.
  20657.  
  20658.  
  20659.  
  20660.              17. MECCA Language Reference                              376
  20661.  
  20662.               [msg_matrix] - ^w^maM
  20663.  
  20664.                 Display the rest of the line only if the current message
  20665.                 area is a NetMail area.
  20666.  
  20667.              [msg_next] - ^w^miN
  20668.  
  20669.                 Display the rest of the line only if the current message-
  20670.                 reading direction is forward (as opposed to backward).
  20671.  
  20672.              [msg_nomsgs] - ^w^mnM
  20673.  
  20674.                 Display the rest of the line only if the current message
  20675.                 area contains no messages.
  20676.  
  20677.              [msg_nonew] - ^w^mnN
  20678.  
  20679.                 Display the rest of the line only if the current message
  20680.                 area does not contain any new messages.
  20681.  
  20682.              [msg_noread] - ^w^mnR
  20683.  
  20684.                 Display the rest of the line only if the user has not read
  20685.                 any of the messages in the current message area.
  20686.  
  20687.               [msg_prior] - ^w^miP
  20688.  
  20689.                 Display the rest of the line only if the current message-
  20690.                 reading direction is backward (as opposed to forward).
  20691.  
  20692.               [no_keypress] - ^wG
  20693.  
  20694.                 Display the rest of the line only if there are no key-
  20695.                 strokes waiting in the input buffer. See also [nostacked].
  20696.                 This differs from [nostacked] in that [no_keypress] only
  20697.                 checks for currently-pending input which has not been proc-
  20698.                 essed, whereas [nostacked] checks for commands entered at a
  20699.                 previous prompt.
  20700.  
  20701.              [nocolor] - ^o^^
  20702.              [nocolour] - Canadian spelling of above
  20703.  
  20704.                 Display the following text (up to the next [endcolor] to-
  20705.                 ken) only to callers who do not have ANSI or AVATAR graph-
  20706.                 ics selected.
  20707.  
  20708.              [norip] - ^oH
  20709.  
  20710.                 Display the following text (up to the next [endrip] token)
  20711.                 only to callers who do not have RIPscrip graphics selected.
  20712.  
  20713.                 For example:
  20714.  
  20715.  
  20716.  
  20717.              17. MECCA Language Reference                              377
  20718.  
  20719.                 [norip]You are not a RIP caller![endrip]
  20720.  
  20721.              [nostacked] - ^wS
  20722.  
  20723.                 Display the rest of the line only if there are no key-
  20724.                 strokes waiting in the key stacking buffer. See also
  20725.                 [no_keypress].
  20726.  
  20727.              [notontoday] - ^wQ
  20728.  
  20729.                 Display the current line only if the user has not logged on
  20730.                 the system previously in the day. (The user must have been
  20731.                 logged on for at least one minute for this token to take
  20732.                 effect.)
  20733.  
  20734.              [novice] - ^wHN
  20735.  
  20736.                 Display the current line only if the user's help level is
  20737.                 set to novice.
  20738.  
  20739.              [ofs]
  20740.  
  20741.                 This token is obsolete.
  20742.  
  20743.              [permanent] - ^wq
  20744.  
  20745.                 Display the current line only if the current user is marked
  20746.                 as being permanent. The permanent flag indicates that the
  20747.                 user should not deleted by any automatic, third-party user
  20748.                 purging utilities.
  20749.  
  20750.               [regular] - ^wHR
  20751.  
  20752.                 Display the rest of the line only if the user has a help
  20753.                 level of regular.
  20754.  
  20755.              [rip] - ^oG
  20756.  
  20757.                 Display the following text (up until the next [endrip] to-
  20758.                 ken) only to those users who have RIPscrip graphics en-
  20759.                 abled. Note that RIPscrip graphics are never shown on the
  20760.                 local console, regardless of the caller's RIPscrip setting.
  20761.  
  20762.                 [rip]You are a RIP caller![endrip]
  20763.  
  20764.              [riphasfile]<name> [,<size>] - ^wY
  20765.  
  20766.                 Display the rest of the line only if the remote caller:
  20767.  
  20768.                 * has RIPscrip graphics enabled, and
  20769.                 * has already received the file <name> with a size of
  20770.                   <size>.
  20771.  
  20772.  
  20773.  
  20774.              17. MECCA Language Reference                              378
  20775.  
  20776.                 The ",<size>" part of the argument is optional. If a <size>
  20777.                 is provided, Maximus will also check the size of the file
  20778.                 on the remote system and ensure that it matches the speci-
  20779.                 fied size. If it does not, Maximus will act as if the file
  20780.                 did not exist.
  20781.  
  20782.                 The "<name>,<size>" argument must be separated from the
  20783.                 rest of the line by a space.
  20784.  
  20785.                 Example #1:
  20786.  
  20787.                 [riphasfile]m_menu.rip,872 |1R00000000m_menu.rip[quit]
  20788.  
  20789.                 This code queries the remote system for a file called
  20790.                 m_menu.rip that is 872 bytes in length. If the file exists,
  20791.                 Maximus displays the rest of the line (which contains the
  20792.                 RIPscrip sequence to display that file).
  20793.  
  20794.                 Example #2:
  20795.  
  20796.                 [riphasfile]m_menu.rip !|1R00000000m_menu.rip[goto quit-
  20797.                 file]
  20798.                 [link]rip\m_menu
  20799.                 [/quitfile]
  20800.  
  20801.                 This code queries the remote system for a file called
  20802.                 m_menu.rip (of any size). If the file exists, Maximus dis-
  20803.                 plays the rest of the line.
  20804.  
  20805.                 This token can be used in conjunction with the [ripsend]
  20806.                 token to allow users to optionally download all of the
  20807.                 RIPscrip scenes used on your BBS.
  20808.  
  20809.               [tagged] - ^w^
  20810.  
  20811.                 Display the rest of the line only if the user has one or
  20812.                 more files currently tagged.
  20813.  
  20814.               [top] - ^oT
  20815.  
  20816.                 Jump back to the top of the file and start the file display
  20817.                 over again.
  20818.  
  20819.  
  20820.              17.9. Multinode Tokens
  20821.  
  20822.              This section describes MECCA tokens that may be useful for
  20823.              systems with more than one node:
  20824.  
  20825.               [apb] - ^wA
  20826.  
  20827.                 This token sends a message to all users currently on-line,
  20828.                 assuming that the IPC features are enabled.
  20829.  
  20830.  
  20831.  
  20832.              17. MECCA Language Reference                              379
  20833.  
  20834.                 Example #1:
  20835.  
  20836.                 [apb][yellow bell]%!User %n just logged on the system%!
  20837.  
  20838.                 Example #2:
  20839.  
  20840.                 Enter a message to send to all users: [readln]
  20841.                 [apb][yellow bell]%!User %n says "%J"%!
  20842.  
  20843.              [chat_avail] - ^wcA
  20844.  
  20845.                 Display the rest of the line only if the user is available
  20846.                 for paging by other users.
  20847.  
  20848.               [chat_notavail] - ^wcN
  20849.  
  20850.                 Display the rest of the line only if the user is not avail-
  20851.                 able for paging by other users.
  20852.  
  20853.               [who_is_on] - ^ww
  20854.  
  20855.                 Execute the internal Who_Is_On menu command.
  20856.  
  20857.  
  20858.              17.10. RIPscrip Graphics
  20859.  
  20860.              This section describes tokens that are useful when creating
  20861.              RIPscrip graphics displays. See also the [riphasfile], [rip],
  20862.              [norip] and [endrip] tokens.
  20863.  
  20864.              [ripdisplay]<file> - ^wv
  20865.  
  20866.                 Instruct the remote system to immediately display a
  20867.                 RIPscrip icon or scene file.
  20868.  
  20869.                 If the remote system does not have the specified file,
  20870.                 [ripdisplay] will automatically send it. Please see
  20871.                 [ripsend] for information on where Maximus looks to find
  20872.                 the file to be sent.
  20873.  
  20874.               [rippath]<path> -^wU
  20875.  
  20876.                 Change the directory where Maximus looks to find RIPscrip
  20877.                 scene files and icons. The default is the RIP Path speci-
  20878.                 fied in the system control file.
  20879.  
  20880.                 For example:
  20881.  
  20882.                 [iflang]1 [rippath]C:\Max\Rip.1
  20883.  
  20884.  
  20885.  
  20886.              17. MECCA Language Reference                              380
  20887.  
  20888.              [ripsend]<file> - ^wV
  20889.  
  20890.                 Send one or more icons or RIPscrip scene files to the re-
  20891.                 mote system for storage only. These files must exist in the
  20892.                 RIP Path directory or the directory specified by the most
  20893.                 recent [rippath] token. (If the file does not exist in the
  20894.                 directory specified by [rippath], Maximus will look for the
  20895.                 file in the default RIP Path directory.)
  20896.  
  20897.                 If the filename specified for [ripsend] or [ripdisplay]
  20898.                 starts with "@", the file is assumed to be an ASCII file on
  20899.                 the local system that contains a list of files to be sent.
  20900.  
  20901.                 Otherwise, <file> must be a simple filename (with no path)
  20902.                 for a file in the current RIPscrip directory, as specified
  20903.                 by the RIP Path statement in the system control file.
  20904.  
  20905.                 If <file> starts with "!",Maximus ignores the fact that the
  20906.                 file may have already been sent during the current session,
  20907.                 and it will query the remote system anyway (and send the
  20908.                 file if the user does not have it).
  20909.  
  20910.                 Examples:
  20911.  
  20912.                 [ripsend]menu.rip f_icon.icn m_icon.icn
  20913.  
  20914.                 This line simply sends the named files.
  20915.  
  20916.                 [ripsend]@c:\max\allicons.lst
  20917.  
  20918.                 This line sends all files listed in the c:\max\allicons.lst
  20919.                 file.
  20920.  
  20921.                 [ripsend]!menu.rip f_icon.icn m_icon.icn
  20922.  
  20923.                 This line sends all files in the named list, regardless of
  20924.                 whether or not Maximus has sent them previously in the ses-
  20925.                 sion. (However, if the remote user has a matching file name
  20926.                 and size, Maximus will not send the file.)
  20927.  
  20928.               [textsize <cols> <rows>] - ^wg
  20929.  
  20930.                 Set the assumed text window size of the remote system. This
  20931.                 token can be used to make "More [Y,n,=]?" prompts appear in
  20932.                 the correct position when working with a RIPscrip scene
  20933.                 that modifies the text window size.
  20934.  
  20935.                 Examples:
  20936.  
  20937.                 [textsize 0 0]
  20938.  
  20939.                 This resets the window size back to the default from the
  20940.                 user file.
  20941.  
  20942.  
  20943.  
  20944.              17. MECCA Language Reference                              381
  20945.  
  20946.                 [textsize 60 0]
  20947.  
  20948.                 This sets the window width to 60 and sets the window height
  20949.                 to the default from the user file.
  20950.  
  20951.                 [textsize 0 32]
  20952.  
  20953.                 This sets the window height to 32 rows and sets the window
  20954.                 width to the default from the user file.
  20955.  
  20956.                 This MECCA command should be used whenever a called
  20957.                 RIPscrip scene reduces the size of the remote text window.
  20958.  
  20959.  
  20960.              17.11. Miscellaneous Token Listing
  20961.  
  20962.              This section contains miscellaneous MECCA tokens that are not
  20963.              specific to one of the other sections:
  20964.  
  20965.              [ckoff] - ^b
  20966.  
  20967.                 Disable <ctrl-c> and <ctrl-k> checking. This prevents the
  20968.                 user from using these keys to abort the current file.
  20969.  
  20970.               [ckon] - ^c
  20971.  
  20972.                 Enable <ctrl-c> and <ctrl-k> checking. This allows the user
  20973.                 to press these keys to abort the current file.
  20974.  
  20975.              [clear_stacked] - ^wO
  20976.  
  20977.                 Clear the user's command stacking buffer to eliminate any
  20978.                 previously-stacked commands.
  20979.  
  20980.              [comment <c>]
  20981.  
  20982.                 This token is a comment. Anything enclosed in a comment to-
  20983.                 ken is ignored by the MECCA compiler.
  20984.  
  20985.               [copy <f>]
  20986.  
  20987.                 This token is a MECCA directive. When MECCA encounters this
  20988.                 token, it copies the file <f> directly into the output
  20989.                 file, without performing any translations or parsing. En-
  20990.                 sure that the filename <f> is inside the square brackets.
  20991.  
  20992.               [decimal]
  20993.  
  20994.                 This token is obsolete.
  20995.  
  20996.  
  20997.  
  20998.              17. MECCA Language Reference                              382
  20999.  
  21000.              [delete]<f> - ^wD<f>
  21001.  
  21002.                 Delete file <f> from disk. External program translation
  21003.                 characters may be used here.
  21004.  
  21005.               [display]<f> - ^oS<f>
  21006.  
  21007.                 Display the named .bbs file. Control is not returned to the
  21008.                 current file after <f> has displayed. External program
  21009.                 translation characters may be used in the filename for <f>,
  21010.                 but you must use a "+" instead of a "%" to begin the trans-
  21011.                 lation sequence. See also [link].
  21012.  
  21013.               [dos]<c> - ^oC<c>
  21014.  
  21015.                 Run the operating system command <c>. This command can in-
  21016.                 clude arguments and external program translation charac-
  21017.                 ters. See also [xtern_*].
  21018.  
  21019.               [enter] - ^a
  21020.  
  21021.                 Display "Press ENTER to continue" and wait for the user to
  21022.                 press <enter>.
  21023.  
  21024.               [hangup] - ^f^n
  21025.  
  21026.                 Hang up and disconnect the current user.
  21027.  
  21028.               [hex]
  21029.  
  21030.                 This token is obsolete.
  21031.  
  21032.              [ibmchars] - ^wd
  21033.  
  21034.                 Display the rest of the line only to those users who have
  21035.                 the IBM Characters option enabled.
  21036.  
  21037.               [include <f>]
  21038.  
  21039.                 This token is a MECCA directive. MECCA reads in the file
  21040.                 <f> and processes it as if it were part of the current
  21041.                 file.
  21042.  
  21043.              [key?]
  21044.  
  21045.                 This token is obsolete.
  21046.  
  21047.               [key_poke]<keys> - ^wP
  21048.  
  21049.                 Insert keystrokes into the keyboard command-stacking
  21050.                 buffer, just as if the user had entered the keys manually.
  21051.                 This token can be used to automatically guide a user
  21052.                 through several commands at once.
  21053.  
  21054.  
  21055.  
  21056.              17. MECCA Language Reference                              383
  21057.  
  21058.                 The <keys> sequence can include a "|" character. This char-
  21059.                 acter will be translated into an empty response.
  21060.  
  21061.                 For example, the following MECCA sequence skips over the
  21062.                 "enter date:" prompt in the new files scan:
  21063.  
  21064.                 [key_poke]|
  21065.                 [newfiles]
  21066.  
  21067.              [language]  - ^oL
  21068.  
  21069.                 Invoke the internal Chg_Language menu option.
  21070.  
  21071.              [link]<f> - ^wL
  21072.  
  21073.                 Display the specified .bbs file. Control is returned to the
  21074.                 current display file after <f> has displayed. Up to 8 dis-
  21075.                 play files can be nested using the [link] token.
  21076.  
  21077.               [log]<s> - ^wA<s>
  21078.  
  21079.                 Add the statement <s> to the system log. The first charac-
  21080.                 ter of <s> must be the log "priority level" for the left-
  21081.                 hand column of the log. The rest of <s> is the log string
  21082.                 to insert. External program translation characters can also
  21083.                 be inserted in this string.
  21084.  
  21085.                 For example:
  21086.  
  21087.                 [log]+User's name is "%n"
  21088.  
  21089.               [menu_cmd <s>]<arg> - ^rr
  21090.  
  21091.                 Invoke the menu command specified by <s>.
  21092.  
  21093.                 For example, [menu_cmd goodbye] invokes the "Goodbye" menu
  21094.                 option. Please see section 18.8 for a list of valid menu
  21095.                 options.
  21096.  
  21097.               [menupath]<p> - ^wM<p>
  21098.  
  21099.                 Sets the current path for *.mnu files to <p>.
  21100.  
  21101.              [mex]<file> - ^wn
  21102.  
  21103.                 Run the MEX program specified by <file>. For example:
  21104.  
  21105.                 [mex]d:\path\filename arg1 arg2 arg3
  21106.  
  21107.               [more] - ^d
  21108.  
  21109.                 Display a "More [Y,n,=]?" prompt.
  21110.  
  21111.  
  21112.  
  21113.              17. MECCA Language Reference                              384
  21114.  
  21115.              [moreoff] - ^k
  21116.  
  21117.                 Disable the automatic "More [Y,n,=]?" prompting feature.
  21118.  
  21119.              [moreon] - ^e
  21120.  
  21121.                 Enable the automatic "More [Y,n,=]?" prompting feature.
  21122.  
  21123.               [msg_checkmail] - ^wC
  21124.  
  21125.                 Invoke the internal mail checker.
  21126.  
  21127.              [newfiles] - ^wF
  21128.  
  21129.                 Invoke a new files scan.
  21130.  
  21131.               [onexit]<f> - ^oF<f>
  21132.  
  21133.                 This sets the On Exit filename for the current display
  21134.                 file. When the current file has finished displaying, Maxi-
  21135.                 mus will display the file indicated by <f>.
  21136.  
  21137.               [pause] - ^f^g
  21138.  
  21139.                 Pause for half a second.
  21140.  
  21141.              [quit] - ^oQ
  21142.  
  21143.                 Quit the current file immediately. If the current file was
  21144.                 displayed with a [link] token, this command will exit back
  21145.                 to the calling display file. See also [exit].
  21146.  
  21147.              [quote] - ^f^a
  21148.  
  21149.                 Display the next quote from the file in the Uses Quote
  21150.                 definition in the system control file.
  21151.  
  21152.              [repeat]<c>[<n>] - ^y<c><n>
  21153.  
  21154.                 Output a sequence of repeated bytes. Maximus will output
  21155.                 the character <c> a total of <n> times. The value for <n>
  21156.                 must normally be contained in square brackets.
  21157.  
  21158.                 For example, this text
  21159.  
  21160.                 [repeat]=[15]
  21161.  
  21162.                 displays the "=" character 15 times.
  21163.  
  21164.              [repeatseq <len>]<s>[<n>] - ^v^y<len><s><n>
  21165.  
  21166.                 Repeat the text string <s> a total of <n> times. The string
  21167.                 <s> must have a length of <len>.
  21168.  
  21169.  
  21170.  
  21171.              17. MECCA Language Reference                              385
  21172.  
  21173.                 For example:
  21174.  
  21175.                 [repeatseq 7]Hello! [10]
  21176.  
  21177.                 The above line displays the phrase "Hello!" followed by a
  21178.                 space (a total of ten times).
  21179.  
  21180.              [string]
  21181.              [subdir]
  21182.              [unsigned]
  21183.  
  21184.                 These tokens are obsolete.
  21185.  
  21186.               [tag_read]<filename> - ^wz
  21187.  
  21188.                 Read a list of tagged files from <filename>. The current
  21189.                 list of tagged files is destroyed.
  21190.  
  21191.               [tag_write]<filename> - ^wZ
  21192.  
  21193.                 Write the current list of tagged files to <filename>. If no
  21194.                 filename is specified, Maximus writes the files to the file
  21195.                 specified by the default_tag_save field in the system lan-
  21196.                 guage file. External program translation characters may be
  21197.                 used in this string.
  21198.  
  21199.               [tune]<name> - ^wu<name>
  21200.  
  21201.                 Play the specified tune from the tunes.bbs file on the lo-
  21202.                 cal console.
  21203.  
  21204.                 For example:
  21205.  
  21206.                 [tune]Yell1
  21207.  
  21208.              [xtern_dos]<c> - ^wXD<c>
  21209.              [xtern_erlvl]<c> - ^wXE<c>
  21210.              [xtern_run]<c> - ^wXR<c>
  21211.  
  21212.                 Run the external program <c>. If you wish to pass arguments
  21213.                 to the external program, simply add the arguments after the
  21214.                 name of the program to execute, separating each argument
  21215.                 with a space. Please see section 6 for more information on
  21216.                 running external programs with Maximus.
  21217.  
  21218.  
  21219.  
  21220.  
  21221.  
  21222.  
  21223.  
  21224.  
  21225.                                                  18. Control File Reference
  21226.  
  21227.              The system control files, \max\*.ctl, are the heart of your
  21228.              BBS. This reference section describes all of the keywords and
  21229.              commands contained within. The keywords are organized by con-
  21230.              trol file and are listed alphabetically.
  21231.  
  21232.              The control files must be compiled using the SILT compiler
  21233.              before Maximus will recognize any changes that you may make.
  21234.              Please see section 8.12 for more information on the SILT com-
  21235.              piler.
  21236.  
  21237.  
  21238.              18.1. SILT Directives
  21239.  
  21240.              Directives are commands that are interpreted only by the SILT
  21241.              compiler; they simply modify SILT's operation and do not pro-
  21242.              duce any output on their own.
  21243.  
  21244.              These directives can be used in any configuration file:
  21245.  
  21246.              Include <filespec>
  21247.  
  21248.                 The Include keyword instructs SILT to process the file
  21249.                 <filespec> as if it were included as part of the current
  21250.                 control file. The Include keyword cannot be used within a
  21251.                 Section statement.
  21252.  
  21253.              Version14 <filespec>
  21254.              Version17 <filespec>
  21255.  
  21256.                 These keywords are obsolete.
  21257.  
  21258.  
  21259.              18.2. System Control File
  21260.  
  21261.              The system control file, max.ctl, is the most important part
  21262.              of any Maximus system. A heavily-commented system control
  21263.              file comes as part of the standard Maximus installation, and
  21264.              in many cases, you can rely on only the comments contained
  21265.              within. However, this section provides a comprehensive refer-
  21266.              ence for all of the commands and definitions in the system.
  21267.  
  21268.  
  21269.              18.2.1. System Section Keyword Listing
  21270.  
  21271.              Dos Close Standard Files
  21272.  
  21273.                 Close all files before running an external program. This
  21274.                 feature should normally be enabled, since it allows exter-
  21275.  
  21276.  
  21277.  
  21278.              18. Control File Reference                                388
  21279.  
  21280.                 nal programs to write to the system log file and manipulate
  21281.                 the area data files.
  21282.  
  21283.              File Access <file >
  21284.  
  21285.                 This is the root name of the privilege level database. This
  21286.                 keyword must come below the File Password keyword. SILT
  21287.                 will create the access data file in the Maximus system di-
  21288.                 rectory when run with the -p or -x switches.
  21289.  
  21290.              File Callers <rootname>
  21291.  
  21292.                 Name of the optional caller log file. This is a binary log
  21293.                 that can be read by third-party utilities (and by using the
  21294.                 call_open and related MEX functions). When the user is
  21295.                 logged off, a 128 byte record is appended to this log file.
  21296.  
  21297.              File Password <filespec>
  21298.  
  21299.                 This keyword tells Maximus where to find the system user
  21300.                 file. The <filespec> parameter must not have an extension.
  21301.                 This file contains log-on and password information for all
  21302.                 users on the system. If you are just starting out with
  21303.                 Maximus and do not yet have a user file, start Maximus us-
  21304.                 ing the "-c" command line parameter.
  21305.  
  21306.              Log File <log_name>
  21307.  
  21308.                 This keyword tells Maximus what to call your system log
  21309.                 file. The system log file is a human-readable version of
  21310.                 the File Callers file. The log describes who called your
  21311.                 system, when they called, and what they did while on-line.
  21312.                 This statement can be overridden from the command line with
  21313.                 the -l parameter.
  21314.  
  21315.              Log Mode <log_type>
  21316.  
  21317.                 This keyword tells Maximus how much information to place in
  21318.                 the system log file. Maximus supports three logging modes
  21319.                 for <log_type>, as shown below in Table 18.1:
  21320.  
  21321.                 Table 18.1 Logging Modes
  21322.  
  21323.                 Type      Description
  21324.  
  21325.                 Trace     Maximus logs all events.
  21326.                 Verbose   Maximus logs most system events, including file
  21327.                           transfers and external programs.
  21328.                 Terse     Maximus only logs major system events, such as
  21329.                           users logging off and errors.
  21330.  
  21331.  
  21332.  
  21333.              18. Control File Reference                                389
  21334.  
  21335.              MCP Pipe <path>
  21336.  
  21337.         OS/2    The <path> parameter specifies the pipe name to use for
  21338.        only!    the MCP server process. The -a command line parameter can
  21339.                 be used to override this value.
  21340.  
  21341.              MCP Sessions <num>
  21342.  
  21343.         OS/2    This keyword sets an upper limit on the maximum number of
  21344.        only!    Maximus sessions that will be running at the same time.
  21345.                 Maximus passes this information to MCP when it starts up.
  21346.                 (MCP uses <num> to determine how many named pipes to cre-
  21347.                 ate.)
  21348.  
  21349.              Multitasker <type>
  21350.  
  21351.          DOS    This keyword is only required if you are running Maximus
  21352.        only!    under a multitasking environment. <type> can be any of the
  21353.                 following:
  21354.  
  21355.                 * DESQview
  21356.                 * DoubleDOS
  21357.                 * PC-MOS
  21358.                 * MSWindows
  21359.                 * None
  21360.  
  21361.              Name <bbs_name>
  21362.  
  21363.                 This keyword contains the name of your BBS. This name will
  21364.                 be shown in a number of .bbs display files and on the "*
  21365.                 Origin:" line for EchoMail areas.
  21366.  
  21367.              No Password Encryption
  21368.  
  21369.                 This flag disables the default password encryption feature.
  21370.                 Enabling this keyword will not decrypt any currently-
  21371.                 encrypted passwords in the user file, but it will prevent
  21372.                 Maximus from automatically encrypting the passwords for new
  21373.                 users. (Maximus will still be able to handle existing en-
  21374.                 tries from the user file that contain encrypted passwords.)
  21375.  
  21376.              No SHARE.EXE
  21377.  
  21378.                 This keyword tells Maximus that you are running MS-DOS ver-
  21379.                 sion 3.3 (or prior) and that you do not have share.exe
  21380.                 loaded. This keyword should only be used as a last resort,
  21381.                 since data file corruption may occur if you try to run in a
  21382.                 multitasking environment without support for share.exe. You
  21383.                 are using this keyword at your own risk. Lanius cannot pro-
  21384.                 vide support for systems that run with this keyword en-
  21385.                 abled.
  21386.  
  21387.  
  21388.  
  21389.              18. Control File Reference                                390
  21390.  
  21391.              Path Inbound <path>
  21392.  
  21393.                 This path tells Maximus where to find the files that are
  21394.                 received by a front end mailer. Maximus will use this di-
  21395.                 rectory if you turn on FTS-0001 file attach support by ena-
  21396.                 bling the Style Attach attribute in a NetMail message area.
  21397.  
  21398.        Warni    If you make this facility available to non-trusted users,
  21399.          ng!    you may compromise the security of files in your inbound
  21400.                 directory. Regular local file attach areas are safe for
  21401.                 all users, but due to the nature of FTS-0001 attaches, you
  21402.                 should only allow trusted users to access a NetMail area
  21403.                 that has the local file attach feature enabled.
  21404.  
  21405.              Path IPC <path>
  21406.  
  21407.          DOS    This keyword is only required for DOS users. Maximus-OS/2
  21408.        only!    automatically uses the MCP communications server to handle
  21409.                 its inter-process communications needs.
  21410.  
  21411.                 This keyword defines the path for the inter-process commu-
  21412.                 nications area. Maximus will use this directory to store
  21413.                 temporary files for the multi-node chat facility. This key-
  21414.                 word must point to an empty directory that you are not us-
  21415.                 ing for any other purpose.
  21416.  
  21417.                 You must have share.exe loaded to use the Path IPC feature.
  21418.  
  21419.              Path Language <path>
  21420.  
  21421.                 This keyword tells Maximus where to find your system lan-
  21422.                 guage files.
  21423.  
  21424.              Path Misc <path>
  21425.  
  21426.                 This keyword tells Maximus where to find miscellaneous sys-
  21427.                 tem display files. Aside from many of the standard .bbs
  21428.                 files, this is also where the function-key files (f*.bbs,
  21429.                 cf*.bbs, af*.bbs, and sf*.bbs) are located. Please see
  21430.                 Appendix D for more information on these files.
  21431.  
  21432.              Path Outbound <path>
  21433.  
  21434.                 This keyword is obsolete.
  21435.  
  21436.              Path System <full_path>
  21437.  
  21438.                 This keyword tells Maximus where to find the main system
  21439.                 files. The <full_path> must be a fully-qualified file
  21440.                 specification, including the drive specifier and leading
  21441.                 backslash. For example, two valid paths are:
  21442.  
  21443.                 C:\Max
  21444.  
  21445.  
  21446.  
  21447.              18. Control File Reference                                391
  21448.  
  21449.                 D:\Bbs\Maximus
  21450.  
  21451.              Path Temp <path>
  21452.  
  21453.                 This keyword tells Maximus the name of a directory that it
  21454.                 can use for storing temporary files. Maximus will routinely
  21455.                 delete files from this directory, so you must not store
  21456.                 anything else here.
  21457.  
  21458.              Reboot
  21459.  
  21460.          DOS    This keyword tells Maximus to activate the FOSSIL
  21461.        only!    "watchdog" feature. This means that the FOSSIL will reboot
  21462.                 the computer if a user drops carrier while running an ex-
  21463.                 ternal program.
  21464.  
  21465.              Snoop
  21466.  
  21467.                 This keyword controls the default state of the "Snoop" set-
  21468.                 ting. When Snoop is enabled, the local console will display
  21469.                 exactly what is shown to the remote caller. If Snoop is
  21470.                 disabled, the local screen will contain just a status line
  21471.                 display, similar to the system log file. Disabling Snoop
  21472.                 will increase performance on a multi-node system.
  21473.  
  21474.                 Snoop can be manually enabled from the SysOp console using
  21475.                 the "N" key.
  21476.  
  21477.              Swap
  21478.  
  21479.          DOS    This keyword instructs Maximus to swap itself out of mem-
  21480.        only!    ory before executing external programs. Maximus will auto-
  21481.                 matically try to swap itself to XMS, EMS and disk (in that
  21482.                 order) when running an external program. Maximus requires
  21483.                 less than 2K of conventional memory when it is swapped out.
  21484.  
  21485.              SysOp <name>
  21486.  
  21487.                 This keyword specifies the name of the system operator.
  21488.                 This keyword does not automatically grant any special ac-
  21489.                 cess rights; only those users with a privilege level high
  21490.                 enough to put them in the SysOp user class are treated as
  21491.                 SysOps.
  21492.  
  21493.                 However, this keyword controls the name that is displayed
  21494.                 by the [sysop_name] MECCA token and in the To: field in a
  21495.                 Leave_Comment message.
  21496.  
  21497.              Task <task_no>
  21498.  
  21499.                 This keyword specifies the default node number for the sys-
  21500.                 tem. The node number can be overridden using the -n command
  21501.                 line parameter.
  21502.  
  21503.  
  21504.  
  21505.              18. Control File Reference                                392
  21506.  
  21507.                 If you are running a multinode system, ensure that all of
  21508.                 your task numbers are non-zero. If you run a copy of Maxi-
  21509.                 mus with a node number of 0, it will not be able to commu-
  21510.                 nicate with the rest of the system.
  21511.  
  21512.              Video <mode>
  21513.  
  21514.          DOS    This keyword only applies to DOS users. Maximus-OS/2 al-
  21515.        only!    ways uses Video IBM.
  21516.  
  21517.                 This keyword specifies the method to be used for local
  21518.                 video display. Table 18.2 lists the video modes supported
  21519.                 for <mode>:
  21520.  
  21521.                 Table 18.2 Video Modes
  21522.  
  21523.                 Mode         Description
  21524.  
  21525.                 BIOS         Maximus writes all output to the screen us-
  21526.                              ing the video BIOS. This mode is almost as
  21527.                              fast as Video IBM, but it will work on some
  21528.                              PCs on which the IBM mode does not.
  21529.                 IBM          Maximus writes directly to the video hard-
  21530.                              ware. This is lightning-fast and is the
  21531.                              quickest way to run Maximus, but it may not
  21532.                              be compatible with some hardware or multi-
  21533.                              taskers.
  21534.                 IBM/snow     This mode is identical to "Video IBM," ex-
  21535.                              cept that Maximus will wait for the vertical
  21536.                              retrace before writing to the video buffer.
  21537.                              This option may reduce flicker on some old
  21538.                              IBM CGA cards.
  21539.  
  21540.  
  21541.  
  21542.              18.2.2. Equipment Section Keyword Listing
  21543.  
  21544.              Answer <cmd>
  21545.  
  21546.                 In WFC mode, when Maximus detects a RING from the modem (as
  21547.                 defined by the Ring keyword), it will send this modem com-
  21548.                 mand in response.
  21549.  
  21550.                 This command is used if you want Maximus to answer the
  21551.                 phone itself, rather than trusting the modem hardware to
  21552.                 pick up the line. For a standard Hayes modem, this keyword
  21553.                 should read:
  21554.  
  21555.                 Answer  ATA|
  21556.  
  21557.                 See the Busy keyword for special characters that can be
  21558.                 used in the <cmd> string.
  21559.  
  21560.  
  21561.  
  21562.              18. Control File Reference                                393
  21563.  
  21564.              Baud Maximum <speed>
  21565.  
  21566.                 This keyword specifies the maximum speed that is supported
  21567.                 by your modem. <speed> can be any of 300, 600, 1200, 2400,
  21568.                 4800, 9600, 19200, or 38400. Maximus-OS/2 also supports a
  21569.                 speed of 57600.
  21570.  
  21571.              Busy <cmd>
  21572.  
  21573.                 This keyword specifies the string that Maximus sends to the
  21574.                 modem after a caller logs off.
  21575.  
  21576.                 Table 18.3 lists the characters in the <cmd> string that
  21577.                 Maximus translates into certain actions:
  21578.  
  21579.                 Table 18.3 Modem Translation Characters
  21580.  
  21581.                 Character     Description
  21582.  
  21583.                 v             Set DTR low
  21584.                 ^             Set DTR high
  21585.                 ~             Pause for one second
  21586.                 `             Pause for 1/20th of a second
  21587.                 |             Send a carriage return
  21588.  
  21589.  
  21590.              Connect <string>
  21591.  
  21592.                 This keyword specifies the string that is returned by the
  21593.                 modem when a connection is successfully established. To de-
  21594.                 termine the speed of the caller, Maximus will parse the
  21595.                 text that the modem sends after this string.
  21596.  
  21597.              Init <cmd>
  21598.  
  21599.                 This keyword specifies the string that Maximus sends when
  21600.                 it needs to initialize the modem. Please see the Busy key-
  21601.                 word for information on special characters that can appear
  21602.                 in this string.
  21603.  
  21604.                 A normal Init string looks like this:
  21605.  
  21606.                 Init   ~v~````|~^``ATH0|
  21607.  
  21608.                 If you want the modem to answer the phone automatically
  21609.                 (and if you have commented out the Answer string), use this
  21610.                 string:
  21611.  
  21612.                 Init   ~v~````|~^``ATH0S0=1|
  21613.  
  21614.                 If you want Maximus to answer the phone itself, use the
  21615.                 first Init string and enable the Answer keyword.
  21616.  
  21617.  
  21618.  
  21619.              18. Control File Reference                                394
  21620.  
  21621.              Mask Carrier <mask>
  21622.  
  21623.          DOS    This keyword tells Maximus which Modem Status Register
  21624.        only!    (MSR) bit to use for detecting on-line callers. This value
  21625.                 is 128 for all modems made for use in North America and
  21626.                 Europe, and it is also 128 for the vast majority of modems
  21627.                 in all other countries. Do not change this value unless
  21628.                 your modem's manual specifically instructs you to do so.
  21629.  
  21630.              Mask Handshaking <flow_control>
  21631.  
  21632.                 This keyword tells Maximus to enable or disable various
  21633.                 types of flow control. The supported types for
  21634.                 <flow_control> are:
  21635.  
  21636.                 * XON
  21637.                 * CTS
  21638.                 * DSR
  21639.  
  21640.                 You must enable XON flow control if you want your users to
  21641.                 be able to use <ctrl-s> and <ctrl-q> to start and stop
  21642.                 screen display.
  21643.  
  21644.                 You must enable CTS flow control if you are using a high
  21645.                 speed modem. Some (but not all) modems also support DSR
  21646.                 flow control.
  21647.  
  21648.              No Critical Handler
  21649.  
  21650.          DOS    Use this command to disable the internal critical error
  21651.        only!    handler. The critical error handler instructs DOS to fail
  21652.                 the operations that would normally halt the system with an
  21653.                 "Abort, Retry, Fail?" error message. Instead, it will print
  21654.                 one of the following error messages:
  21655.  
  21656.                 Critical error reading/writing drive X:
  21657.                 Critical error accessing device COMx
  21658.  
  21659.              Output <port>
  21660.  
  21661.                 This keyword sets the default COM port for modem output.
  21662.  
  21663.          DOS    The DOS version of Maximus supports <port> values of
  21664.        only!    "Com1" through "Com8" and "Local".
  21665.  
  21666.         OS/2    The OS/2 version of Maximus provides support for "Com1" up
  21667.        only!    to the highest COM port that you have installed, in addi-
  21668.                 tion to the "Local" port.
  21669.  
  21670.                 For either operating system, when using ports higher than
  21671.                 COM2, note that your FOSSIL (or OS/2 communications driver)
  21672.                 and modem hardware must also specifically support the port
  21673.  
  21674.  
  21675.  
  21676.              18. Control File Reference                                395
  21677.  
  21678.                 that you wish to use. Check with your FOSSIL or driver
  21679.                 manuals for details on this.
  21680.  
  21681.                 This setting can be overridden from the command line. The
  21682.                 -p command line parameter instructs Maximus to use an al-
  21683.                 ternate COM port, while the -k parameter instructs Maximus
  21684.                 to log on locally.
  21685.  
  21686.              Ring <string>
  21687.  
  21688.                 This keyword specifies the response sent by your modem when
  21689.                 the phone is ringing. When Maximus receives this string, it
  21690.                 will send the string specified by the Answer keyword.
  21691.  
  21692.              Send Break to Clear Buffer
  21693.  
  21694.                 This keyword can only be used by owners of U.S. Robotics
  21695.                 Courier or Sportster modems.
  21696.  
  21697.                 This keyword instructs Maximus to send a BREAK signal when-
  21698.                 ever it needs to clear the transmit buffer. This feature
  21699.                 makes hotkeys slightly more responsive.
  21700.  
  21701.                 To enable this feature, you must include the "&Y0" parame-
  21702.                 ter in your USR modem's initialization string. Otherwise,
  21703.                 the modem may transmit the BREAK signal to the remote modem
  21704.                 instead of clearing its transmit buffer.
  21705.  
  21706.                 At the time of writing, only the U.S. Robotics modems im-
  21707.                 plement this feature correctly. Do not try to use Send
  21708.                 Break to Clear Buffer with modems from other manufacturers.
  21709.  
  21710.  
  21711.              18.2.3. Matrix/EchoMail Keyword Listing
  21712.  
  21713.              Address [zone:]<net/node>[.point]
  21714.  
  21715.                 This keyword specifies the FidoNet-compatible network ad-
  21716.                 dress used by Maximus. This address is inserted in message
  21717.                 headers when writing NetMail or EchoMail messages. You may
  21718.                 specify up to 16 addresses, but the first address will be
  21719.                 used by default.
  21720.  
  21721.                 If you are running Maximus in a point configuration, the
  21722.                 first Address line must specify your full 4D point address.
  21723.                 The second Address line should specify your "fakenet" ad-
  21724.                 dress. If you have no fakenet address, the second Address
  21725.                 line should specify your host's address.
  21726.  
  21727.  
  21728.  
  21729.              18. Control File Reference                                396
  21730.  
  21731.              After EchoMail Exit <errorlevel>
  21732.  
  21733.                 This keyword tells Maximus which errorlevel to use when a
  21734.                 user enters EchoMail messages. This errorlevel will super-
  21735.                 sede the After Edit errorlevel.
  21736.  
  21737.              After Edit Exit <errorlevel>
  21738.  
  21739.                 This keyword tells Maximus which errorlevel to use when a
  21740.                 user enters NetMail messages. This errorlevel is superseded
  21741.                 by the After EchoMail errorlevel.
  21742.  
  21743.              After Local Exit <errorlevel>
  21744.  
  21745.                 This keyword tells Maximus which errorlevel to use when a
  21746.                 user enters local messages. This errorlevel is superseded
  21747.                 by both the After EchoMail and After Edit errorlevels.
  21748.  
  21749.              FidoUser <filespec>
  21750.  
  21751.                 This keyword specifies the name and location of a
  21752.                 user/address list (in standard fidouser.lst format). This
  21753.                 file can be used for performing automatic address lookups
  21754.                 when writing NetMail messages.
  21755.  
  21756.                 The list must be stored as a sorted ASCII text file. Each
  21757.                 line must be exactly 60 columns wide in the format shown
  21758.                 below:
  21759.  
  21760.                 Davis, Bob                         1:106/114
  21761.                 Doe, Jane                            1:13/42
  21762.                 Doe, John                              1:1/2
  21763.                 Dudley, S                          1:249/106
  21764.  
  21765.              Gate NetMail
  21766.  
  21767.                 This keyword instructs Maximus to "gate route" interzone
  21768.                 NetMail through the FidoNet zone gate. This function is
  21769.                 handled by the Squish mail processor, so this keyword
  21770.                 should normally be left commented out.
  21771.  
  21772.              Log EchoMail <filespec>
  21773.  
  21774.                 This keyword instructs Maximus to create a log of EchoMail
  21775.                 messages entered by the user. If this keyword is enabled
  21776.                 and a Tag keyword is specified for a message area, Maximus
  21777.                 will write the tag for that message area to <filespec> when
  21778.                 the caller logs off.
  21779.  
  21780.                 This file can then be used by an external mail processor
  21781.                 (such as Squish) to scan the specified areas for outgoing
  21782.                 mail.
  21783.  
  21784.  
  21785.  
  21786.              18. Control File Reference                                397
  21787.  
  21788.              Message Edit <action> <attribute> <priv>
  21789.  
  21790.                 The Message Edit keyword series tells Maximus what to do
  21791.                 when a user enters a NetMail message.
  21792.  
  21793.                 <action> can be one of "Ask" or "Assume." For Ask, Maximus
  21794.                 will ask the user whether or not the specified attribute
  21795.                 should be set. For Assume, Maximus will automatically set
  21796.                 the attribute without asking the user.
  21797.  
  21798.                 If the full-screen reader is enabled, <action> has a
  21799.                 slightly different functionality. Attributes marked with
  21800.                 Assume will be forced on when the user enters a message.
  21801.                 Maximus will not explicitly prompt the user for an attrib-
  21802.                 ute when Ask is used, but it will allow the user to select
  21803.                 that attribute from the message attribute field (above the
  21804.                 message date).
  21805.  
  21806.                 Valid values for <attribute> are:
  21807.  
  21808.                 * Private
  21809.                 * Crash
  21810.                 * FileAttach
  21811.                 * KillSent
  21812.                 * Hold
  21813.                 * FromFile
  21814.                 * FileReq
  21815.                 * UpdateReq
  21816.                 * LocalAttach
  21817.  
  21818.              Message Send Unlisted <priv> <cost>
  21819.  
  21820.                 This keyword controls the privilege level required to send
  21821.                 NetMail to nodes which are not in the system nodelist. If
  21822.                 the user's privilege level is less than <priv>, Maximus
  21823.                 will not allow the user to send the message. If the user's
  21824.                 privilege level is at least <priv>, Maximus will charge the
  21825.                 user <cost> cents for sending the message.
  21826.  
  21827.              Message Show <item> to <priv>
  21828.  
  21829.                 This keyword tells Maximus to display message control in-
  21830.                 formation to certain groups of users.
  21831.  
  21832.                 <item> can be any of the items in Table 18.4 below. To be
  21833.                 able to view the specified item, a user must have a privi-
  21834.                 lege level of at least <priv>.
  21835.  
  21836.                 Table 18.4 Message Show Items
  21837.  
  21838.                 Item         Description
  21839.  
  21840.                 Ctl_A        This allows the user to view the <ctrl-a>
  21841.  
  21842.  
  21843.  
  21844.              18. Control File Reference                                398
  21845.  
  21846.                              "kludge lines" in EchoMail messages. This
  21847.                              ability can also be toggled using the
  21848.                              Msg_Kludges menu option.
  21849.                 Seenby       This allows the user to view the "SEEN-BY"
  21850.                              information at the bottom of an EchoMail
  21851.                              message.
  21852.                 Private      This allows the user to read private mail,
  21853.                              regardless of the message's addressee. This
  21854.                              ability is normally only granted to SysOps.
  21855.                              (Normally, users can only see private mes-
  21856.                              sages which are to or from themselves.)
  21857.  
  21858.  
  21859.  
  21860.              Nodelist Version <version>
  21861.  
  21862.                 This keyword specifies the FidoNet nodelist format to use
  21863.                 when sending NetMail messages.
  21864.  
  21865.                 <version> can be any of the following formats:
  21866.  
  21867.                 * 5
  21868.                 * 6
  21869.                 * 7
  21870.                 * FD (FrontDoor)
  21871.  
  21872.                 The first three options specify the "Version5," "Version6"
  21873.                 and "Version7" nodelist formats (respectively). The "FD"
  21874.                 option specifies the FrontDoor nodelist format. Maximus ex-
  21875.                 pects to find the nodelist files in the directory specified
  21876.                 by Path NetInfo.
  21877.  
  21878.                 However, Maximus can send NetMail even without a nodelist;
  21879.                 to do so, you must first uncomment the Message Send Un-
  21880.                 listed keyword and set the privilege level appropriately.
  21881.  
  21882.                 Next, go to directory specified by Path NetInfo and create
  21883.                 a zero-length file called nodelist.idx. The following DOS
  21884.                 command can be used to accomplish this task:
  21885.  
  21886.                 REM > NODELIST.IDX
  21887.  
  21888.         OS/2    The above command only works from a DOS session. The OS/2
  21889.        only!    command interpreter will not create 0-length files, so you
  21890.                 must go to DOS to execute this command.
  21891.  
  21892.                 Once this has been done, Maximus will be able to send and
  21893.                 receive NetMail without a nodelist.
  21894.  
  21895.              Path NetInfo <path>
  21896.  
  21897.                 This keyword tells Maximus where to find your system node-
  21898.                 list files.
  21899.  
  21900.  
  21901.  
  21902.              18. Control File Reference                                399
  21903.  
  21904.              18.2.4. Session Section Keyword Listing
  21905.  
  21906.              After Call Exit <errorlevel>
  21907.  
  21908.                 This keyword tells Maximus which errorlevel to use after a
  21909.                 caller logs off (without leaving any messages).
  21910.  
  21911.              Alias System
  21912.  
  21913.                 This keyword tells Maximus to display the user's alias in
  21914.                 situations where it would normally display the user's name.
  21915.                 This setting applies to user lists, to the multinode chat
  21916.                 facility, and in message areas. (However, you can explic-
  21917.                 itly force the use of real names in a message area using
  21918.                 the Style RealName keyword.)
  21919.  
  21920.                 The Ask Alias keyword can also be used in conjunction with
  21921.                 Alias System to prompt new users for an alias at log-on.
  21922.  
  21923.                 Table 18.5 describes the various combinations of the two
  21924.                 keywords:
  21925.  
  21926.                 Table 18.5 Ask Alias and Alias System Options
  21927.                                             Ask Alias
  21928.  
  21929.                                       Yes                     No
  21930.  
  21931.                              New users are          New users are not
  21932.                              prompted for an alias  prompted for an alias
  21933.                              at log-on. By de-      at log-on. If the user
  21934.                              fault, messages en-    selects an alias in
  21935.                              tered by users will    the Change Setup sec-
  21936.                         Yes  use the alias unless   tion, this setting
  21937.                              Style RealName is      causes Maximus to
  21938.                              specified for that     function as if both
  21939.                              area. Users show up    Ask Alias and Alias
  21940.                              in Who Is On as their  System were enabled in
  21941.                              aliases. The alias     the system control
  21942.                              field is searched and  file.
  21943.                              displayed when doing
  21944.                              a Userlist.
  21945.  
  21946.                 Alias        New users are          No alias use whatso-
  21947.                 System       prompted for an alias  ever.
  21948.                              at log-on. By de-
  21949.                              fault, messages en-
  21950.                              tered will use the
  21951.                              user's real name un-
  21952.                         No   less Style Alias is
  21953.                              used in the message
  21954.                              area definition. Us-
  21955.                              ers show up as their
  21956.  
  21957.  
  21958.  
  21959.              18. Control File Reference                                400
  21960.  
  21961.                              real names in Who is
  21962.                              On. The user's real
  21963.                              name is searched and
  21964.                              displayed when doing
  21965.                              a Userlist.
  21966.  
  21967.  
  21968.              Area Change Keys <keylist>
  21969.  
  21970.                 This keyword tells Maximus which keys to support on the
  21971.                 Area Change menu for message and file areas. The first key
  21972.                 in <keylist> is used to select the prior area. The second
  21973.                 key in <keylist> is used to select the next area. The third
  21974.                 key in <keylist> is used to select the area menu.
  21975.  
  21976.                 In addition to the keys specified here, the user will al-
  21977.                 ways be able to use the "[", "]" and "?" keys to select the
  21978.                 prior area, next area, and area list (respectively).
  21979.  
  21980.              Ask Phone
  21981.  
  21982.                 This keyword tells Maximus to prompt new users to enter a
  21983.                 phone number at log-on. This information is stored in the
  21984.                 user file.
  21985.  
  21986.              Ask Alias
  21987.  
  21988.                 This keyword tells Maximus to prompt new users to enter an
  21989.                 alias at log-on. See the Alias System keyword for more de-
  21990.                 tails.
  21991.  
  21992.              Attach Archiver <arctype>
  21993.  
  21994.                 This keyword specifies the storage type to use for com-
  21995.                 pressed file attaches. The archiver specified by <arctype>
  21996.                 must be a valid archiver defined in compress.cfg.
  21997.  
  21998.              Attach Base <root>
  21999.  
  22000.                 This keyword specifies the root name of the file attach da-
  22001.                 tabase. This keyword should specify only the path and up to
  22002.                 four letters for the root of the database name. A number of
  22003.                 additional database files are created using the root name.
  22004.  
  22005.                 For example, given the following statement:
  22006.  
  22007.                 Attach Base C:\Max\Att
  22008.  
  22009.                 Maximus will create the following database files:
  22010.  
  22011.                 C:\Max\Attmsg.db
  22012.                 C:\Max\Attname.i00
  22013.                 C:\Max\Attfile.i01
  22014.  
  22015.  
  22016.  
  22017.              18. Control File Reference                                401
  22018.  
  22019.                 C:\Max\Attfile.i02
  22020.  
  22021.              Attach Path <path>
  22022.  
  22023.                 This keyword specifies the default holding location for lo-
  22024.                 cal file attaches. Unless otherwise specified, local file
  22025.                 attaches will be stored in this area. This directory can be
  22026.                 overridden on an area-by-area basis using the AttachPath
  22027.                 keyword in the message area control file.
  22028.  
  22029.              Charset Swedish
  22030.  
  22031.                 Enable internal support for the Swedish 7-bit character
  22032.                 set. You must also edit english.mad and modify the LBRACKET
  22033.                 and RBRACKET definitions to provide proper support for this
  22034.                 character set.
  22035.  
  22036.              Charset Chinese
  22037.  
  22038.                 Enable internal support for the Chinese character set. The
  22039.                 Chinese character set provides for the "BIG5" two-byte
  22040.                 codes used by most Chinese programs.
  22041.  
  22042.              Chat Capture On
  22043.  
  22044.                 This keyword instructs Maximus to automatically enable the
  22045.                 chat capture buffer when entering SysOp chat mode, instead
  22046.                 of forcing the SysOp to press <alt-c> to manually enable
  22047.                 the buffer. This feature does not work when an external
  22048.                 chat program is enabled.
  22049.  
  22050.              Chat External <prog_name>
  22051.  
  22052.                 This keyword tells Maximus to use an external program for
  22053.                 chatting instead of using the internal chat routine. Maxi-
  22054.                 mus will run <prog_name> instead of the internal chat pro-
  22055.                 gram when the SysOp presses <alt-c> on the local console.
  22056.  
  22057.                 To use a MEX program as an "external" chat program, specify
  22058.                 a ":" in front of the name of the program. For example:
  22059.  
  22060.                 Chat External   :M\Mexchat
  22061.  
  22062.              Check ANSI
  22063.  
  22064.                 This keyword instructs Maximus to query the remote terminal
  22065.                 about ANSI support whenever a user logs on with ANSI graph-
  22066.                 ics enabled. If the user's terminal does not report that it
  22067.                 supports ANSI, Maximus will prompt the user to disable ANSI
  22068.                 graphics.
  22069.  
  22070.                 This keyword is disabled by default. A number of ANSI-
  22071.                 supporting terminal programs do not support the query that
  22072.  
  22073.  
  22074.  
  22075.              18. Control File Reference                                402
  22076.  
  22077.                 Maximus uses in this check, and on occasion, Maximus may
  22078.                 assume that a true ANSI-compatible terminal does not sup-
  22079.                 port ANSI.
  22080.  
  22081.              Check RIP
  22082.  
  22083.                 This keyword instructs Maximus to query the remote terminal
  22084.                 about RIPscrip graphics support. If the user's terminal
  22085.                 program does not support RIPscrip, Maximus will prompt the
  22086.                 user to disable RIPscrip graphics.
  22087.  
  22088.                 This keyword is enabled by default. All RIPscrip programs
  22089.                 must support the "do you support RIP" query used by Maxi-
  22090.                 mus, so this keyword helps to ensure that Maximus only
  22091.                 sends RIPscrip graphics to terminal programs that support
  22092.                 it.
  22093.  
  22094.              Comment Area <area>
  22095.  
  22096.                 This keyword tells Maximus where to place log-off message
  22097.                 left by users. This area will also be used for messages
  22098.                 created with the [leave_comment] MECCA token.
  22099.  
  22100.              Edit Disable <option>
  22101.  
  22102.                 This keyword tells Maximus to disable certain editor-
  22103.                 related options.
  22104.  
  22105.                 <option> must be one of the following:
  22106.  
  22107.                 * MaxEd
  22108.                 * UserList
  22109.  
  22110.                 Selecting MaxEd tells Maximus to disable the MaxEd editor.
  22111.                 All users will be forced to use the line editor.
  22112.  
  22113.                 Selecting UserList tells Maximus to disable the "user list"
  22114.                 feature when leaving private messages in local message ar-
  22115.                 eas. (By default, users can enter "?" at the To: prompt to
  22116.                 get a list of users on the system.)
  22117.  
  22118.              FileData <name>
  22119.  
  22120.                 This keyword tells Maximus the root filename to use when
  22121.                 creating the file area data file. Maximus stores all infor-
  22122.                 mation related to file areas in files named <name>.dat and
  22123.                 <name>.idx.
  22124.  
  22125.              File Date <type> [format]
  22126.  
  22127.                 This keyword tells Maximus how to display dates to the
  22128.                 user. Maximus supports a number of data formats, including
  22129.                 U.S., Canadian/British, Japanese and Scientific.
  22130.  
  22131.  
  22132.  
  22133.              18. Control File Reference                                403
  22134.  
  22135.                 In addition, Maximus can be instructed to retrieve file
  22136.                 dates and sizes directly from the directory entry, or it
  22137.                 can obtain that information from the file list itself.
  22138.  
  22139.                 If <type> is Automatic, Maximus will look at the file's di-
  22140.                 rectory entry to determine the file's size and date.
  22141.  
  22142.                 If <type> is Manual, Maximus will assume that the size and
  22143.                 date information is stored as part of the comment in the
  22144.                 files.bbs listing for the file area.
  22145.  
  22146.                 The automatic and manual dates can be overridden on an
  22147.                 area-by-area basis using the Type DateAuto, Type DateList
  22148.                 and Type DateManual keywords.
  22149.  
  22150.                 [format] is the optional format to use when displaying file
  22151.                 dates. It can be any of the following options:
  22152.  
  22153.                 mm-dd-yy (U.S. - default)
  22154.                 dd-mm-yy (Canadian/British)
  22155.                 yy-mm-dd (Japanese)
  22156.                 yymmdd   (Scientific)
  22157.  
  22158.                 If <type> is Automatic, the format above will be used when
  22159.                 displaying the dates from the file directory.
  22160.  
  22161.                 If <type> is Manual, Maximus will use the above date format
  22162.                 when inserting dated entries in the files.bbs catalog for
  22163.                 uploads. You must manually insert dates for any preexisting
  22164.                 files in the file areas.
  22165.  
  22166.                 The format specified by [format] is also used when prompt-
  22167.                 ing the user for a date during a new files scan.
  22168.  
  22169.                 Examples:
  22170.  
  22171.                 File Date Automatic dd-mm-yy
  22172.  
  22173.                 This line tells Maximus to automatically determine the
  22174.                 dates and sizes of files from their directory entries, and
  22175.                 also to display dates using a Canadian format.
  22176.  
  22177.                 File Date Manual yy-mm-dd
  22178.  
  22179.                 This line tells Maximus to expect to find file sizes and
  22180.                 dates inserted directly into files.bbs, and when inserting
  22181.                 upload descriptions into the file catalog, to insert dates
  22182.                 using the Japanese date format.
  22183.  
  22184.              FileList Margin <col>
  22185.  
  22186.                 This keyword instructs Maximus to indent long files.bbs de-
  22187.                 scriptions by a particular offset for the second and subse-
  22188.  
  22189.  
  22190.  
  22191.              18. Control File Reference                                404
  22192.  
  22193.                 quent lines. This may be useful if an external program is
  22194.                 used to add a "download counter" to file descriptions; the
  22195.                 margin can be increased to create a hanging indent, thereby
  22196.                 placing the download counter in a separate column.
  22197.  
  22198.              First File Area <area>
  22199.  
  22200.                 New users will be placed in the file area specified by
  22201.                 <area> when they first log on. All users must be able to
  22202.                 access at least one file area at all times.
  22203.  
  22204.              First Menu <menu>
  22205.  
  22206.                 This keyword defines the name of the menu to be shown after
  22207.                 Maximus finishes displaying welcome.bbs.
  22208.  
  22209.              First Message Area <area>
  22210.  
  22211.                 New users will be placed in the message area specified by
  22212.                 <area> when they first log on. All users must be able to
  22213.                 access at least one file area at all times.
  22214.  
  22215.              Format Date <date_format>
  22216.  
  22217.                 The Format Date keyword controls the format of dates dis-
  22218.                 played by Maximus.
  22219.  
  22220.                 This format is used to display dates in message headers and
  22221.                 in various other places throughout the system. The date
  22222.                 format is output to the user exactly as specified, except
  22223.                 for several special translation characters.
  22224.  
  22225.                 Table 18.6 describes the case-sensitive date translation
  22226.                 characters supported by Maximus:
  22227.  
  22228.                 Table 18.6 Date Format Characters
  22229.  
  22230.                 Format   Description
  22231.  
  22232.                 %A       Either "am" or "pm," as appropriate.
  22233.                 %B       The month (in decimal).
  22234.                 %C       The month as an abbreviated text string.
  22235.                 %D       The day-of-month (in decimal).
  22236.                 %E       The hour (in the range of 1 to 12).
  22237.                 %H       The hour (in the range of 0 to 23).
  22238.                 %M       The minute.
  22239.                 %S       The second.
  22240.                 %Y       The year (without the century).
  22241.                 %%       A single percent sign.
  22242.  
  22243.  
  22244.  
  22245.                 Examples:
  22246.  
  22247.  
  22248.  
  22249.              18. Control File Reference                                405
  22250.  
  22251.                 %E:%M%A
  22252.  
  22253.                 This translates to the time in a 12-hour format. An example
  22254.                 time shown with this format would be "08:23pm".
  22255.  
  22256.                 %H:%M:%S
  22257.  
  22258.                 This translates to the time in a 24-hour format, including
  22259.                 seconds. An example time shown with this format would be
  22260.                 "20:23:15".
  22261.  
  22262.                 %B-%D-%Y
  22263.  
  22264.                 This translates to the current date in a numeric format. An
  22265.                 example date shown with this format would be "07-16-95".
  22266.  
  22267.                 %D %C %Y
  22268.  
  22269.                 This translates to the current date in mixed format, with a
  22270.                 numeric day-of-month, an abbreviated month, and a numeric
  22271.                 year. An example date shown with this format would be "01
  22272.                 Aug 95."
  22273.  
  22274.              Format FileFormat <format>
  22275.              Format FileHeader <format>
  22276.              Format FileFooter <format>
  22277.              Format MsgFormat <format>
  22278.              Format MsgHeader <format>
  22279.              Format MsgFooter <format>
  22280.  
  22281.                 These keywords tell Maximus how to display the message and
  22282.                 file area lists that are generated when no custom Uses
  22283.                 MsgAreas or Uses FileAreas files are defined.
  22284.  
  22285.                 When displaying a standard message or file area listing,
  22286.                 the MsgHeader (or the FileHeader, as appropriate) is dis-
  22287.                 played at the top of the screen. Next, for each area to be
  22288.                 displayed, one copy of the MsgFormat or FileFormat string
  22289.                 is displayed. Finally, after displaying all of the areas,
  22290.                 Maximus displays the MsgFooter or FileFooter string.
  22291.  
  22292.                 These strings can contain a number of optional formatting
  22293.                 characters in addition to standard ASCII text. The percent
  22294.                 sign ("%") is used as an initiator for the formatting se-
  22295.                 quences. Anything not preceded by a percent sign is passed
  22296.                 directly on to the user.
  22297.  
  22298.                 The format of each control sequence is given below:
  22299.  
  22300.                 %[-][min][.max]<format_char>
  22301.  
  22302.                 Everything except for <format_char> is optional and may be
  22303.                 omitted.
  22304.  
  22305.  
  22306.  
  22307.              18. Control File Reference                                406
  22308.  
  22309.                 The optional "-", if present, specifies that the output of
  22310.                 this formatting character must be left-justified.
  22311.  
  22312.                 The optional min value specifies the minimum width for the
  22313.                 output of this formatting character. When used in conjunc-
  22314.                 tion with the "-" character, the output will be left-
  22315.                 justified. Without the "-" character, the field will be
  22316.                 right-justified.
  22317.  
  22318.                 The optional .max value specifies the maximum width for the
  22319.                 output of this formatting character. If the data field is
  22320.                 longer than max, the field is truncated. The period (".")
  22321.                 in front of the max value is not optional.
  22322.  
  22323.                 format_char specifies the type of output to display. This
  22324.                 character is case-sensitive. The supported characters are
  22325.                 listed in Table 18.7:
  22326.  
  22327.                 Table 18.7 MsgFormat/FileFormat Characters
  22328.  
  22329.                 Character    Description
  22330.  
  22331.                 #            Display the name of the current area.
  22332.                 *            In a MsgFormat statement, this character dis-
  22333.                              plays an asterisk ("*") if the user has un-
  22334.                              read messages in the specified area. Other-
  22335.                              wise, this character displays a space (" ").
  22336.                              (When displaying a list of areas from the
  22337.                              Msg_Tag menu option, this token is also used
  22338.                              to indicate whether or not a message area is
  22339.                              tagged.)
  22340.                 a            The name of the current area with the divi-
  22341.                              sion prefix removed.
  22342.                 d            The name of the current division.
  22343.                 c            When specified in the format "%#.$c", Maximus
  22344.                              will skip the next "$" characters in the
  22345.                              MsgFormat or FileFormat sequence after every
  22346.                              "#"th area is processed. (For example, the
  22347.                              sequence "%2.3cABC" instructs Maximus to dis-
  22348.                              play the sequence "ABC" for every second
  22349.                              area.)
  22350.                 f            Display a .bbs file. The name of the file to
  22351.                              display must immediately follow the "%f" to-
  22352.                              ken. The name of the file must be separated
  22353.                              from the remainder of the string with a
  22354.                              space. (When instructed to display a file,
  22355.                              Maximus will always display that file before
  22356.                              showing any of the other text in the MsgFor-
  22357.                              mat or FileFormat string.)
  22358.                 n            Display the area's description (from the Desc
  22359.                              keyword in the area definition).
  22360.                 t            Display the tag for a message area, as speci-
  22361.                              fied in the Tag keyword in the area defini-
  22362.  
  22363.  
  22364.  
  22365.              18. Control File Reference                                407
  22366.  
  22367.                              tion.
  22368.                 x            Display the next two characters in the se-
  22369.                              quence as a single character. The following
  22370.                              two characters must be hexadecimal digits
  22371.                              that represent a single character.
  22372.  
  22373.  
  22374.                 Examples:
  22375.  
  22376.                 %-15.15t
  22377.  
  22378.                 This translates into the "echo tag" for the current message
  22379.                 area, left justified and exactly fifteen characters long
  22380.                 (padded with spaces).
  22381.  
  22382.                 %30.30n
  22383.  
  22384.                 This translates into the name of the current message area,
  22385.                 right justified to make the field exactly 30 characters
  22386.                 long.
  22387.  
  22388.                 %*%2# / %-25.25n %2c%x0a
  22389.  
  22390.                 This statement causes Maximus to display the area number
  22391.                 for each area, followed by a space and a forward slash, an-
  22392.                 other space, and the area name (left-justified to a maximum
  22393.                 length of 25 characters). After every second area, Maximus
  22394.                 displays a linefeed (ASCII 12, or 0a in hexadecimal), ef-
  22395.                 fectively creating a two-column area display. Finally, if
  22396.                 an area contained new messages, a "*" would be displayed
  22397.                 beside the area number.
  22398.  
  22399.              Format Time <format>
  22400.  
  22401.                 The Format Time keyword controls the format of times dis-
  22402.                 played by Maximus.
  22403.  
  22404.                 This format is used to display times in message headers and
  22405.                 in various other places throughout the system. The times
  22406.                 format is output to the user exactly as specified, except
  22407.                 for several special translation characters.
  22408.  
  22409.                 Please see the description of the Format Date keyword for
  22410.                 information on the supported translation characters.
  22411.  
  22412.              Highest FileArea <area>
  22413.  
  22414.                 This keyword specifies the highest file area number that
  22415.                 can be viewed using the File_Locate and File_Area menu op-
  22416.                 tions. See also the Type Hidden keyword in the file area
  22417.                 control file.
  22418.  
  22419.  
  22420.  
  22421.              18. Control File Reference                                408
  22422.  
  22423.              Highest MsgArea <area>
  22424.  
  22425.                 This keyword specifies the highest message area number that
  22426.                 can be viewed using the Msg_Browse and Msg_Area menu op-
  22427.                 tions. See also the Style Hidden keyword in the message
  22428.                 area control file.
  22429.  
  22430.              Input Timeout <mins>
  22431.  
  22432.                 This tells Maximus to hang up on callers after <mins> min-
  22433.                 utes of inactivity. The default value is 4 minutes. This
  22434.                 keyword can specify a range of 1 to 255 minutes.
  22435.  
  22436.              Kill Attach <type> [priv]
  22437.  
  22438.                 This keyword determines how to handle automatic disposing
  22439.                 of a file when a file attach is received.
  22440.  
  22441.                 <type> must be one of the keywords from Table 18.8:
  22442.  
  22443.                 Table 18.8 Kill Attach Types
  22444.  
  22445.                 Type       Description
  22446.  
  22447.                 Never      An attached file is never deleted automati-
  22448.                            cally.  (The attached file may be deleted by
  22449.                            manually deleting the message containing the
  22450.                            attach.)
  22451.                 Always     An attached file is always deleted after a suc-
  22452.                            cessful download.
  22453.                 Ask        Ask the user if the file should be removed. If
  22454.                            a privilege level is specified and the user's
  22455.                            privilege level is less than this level, the
  22456.                            user is not asked and the file is removed auto-
  22457.                            matically.
  22458.  
  22459.  
  22460.              Kill Private <when>
  22461.  
  22462.                 This keyword controls Maximus's handling of private mes-
  22463.                 sages in local message areas.
  22464.  
  22465.                 <when> can be any of the values from Table 18.9:
  22466.  
  22467.                 Table 18.9 Kill Private Types
  22468.  
  22469.                 Type      Description
  22470.  
  22471.                 Always    Maximus always kills a private message after it
  22472.                           has been read by the recipient.
  22473.                 Ask       Maximus asks the user whether or not to kill a
  22474.                           private message.
  22475.  
  22476.  
  22477.  
  22478.              18. Control File Reference                                409
  22479.  
  22480.                 Never     Maximus never kills a private message automati-
  22481.                           cally.
  22482.  
  22483.  
  22484.              Local Editor [!][@]<editor_cmd>
  22485.  
  22486.                 This keyword tells Maximus to use <editor_cmd> as an exter-
  22487.                 nal message editor for local users, rather than using the
  22488.                 internal MaxEd editor.
  22489.  
  22490.                 With this keyword enabled, Maximus will execute
  22491.                 <editor_cmd> whenever a local user needs to compose a mes-
  22492.                 sage. If the message being created is a reply to another
  22493.                 message, Maximus will quote the original and place it in a
  22494.                 file called msgtmp##.$$$ before invoking the editor, where
  22495.                 ## is the current task number in hexadecimal.
  22496.  
  22497.                 After your editor returns, Maximus expects to find the fi-
  22498.                 nal message in msgtmp##.$$$, regardless of whether or not
  22499.                 the message was a reply.
  22500.  
  22501.                 Normally, the Local Editor keyword only applies to users
  22502.                 who are logged in at the local console. However, if the
  22503.                 first character of the editor name is a "@", certain remote
  22504.                 users will also be allowed to use the "local" editor. See
  22505.                 the MailFlags Editor and MailFlags LocalEditor keywords in
  22506.                 the access control file for information on enabling this
  22507.                 feature.
  22508.  
  22509.                 Finally, if you place the sequence %s inside the
  22510.                 <editor_cmd> string, Maximus will replace the "%s" with the
  22511.                 name of the temporary file to be edited. This can be useful
  22512.                 in a multitasking situation if you do not want to hard-code
  22513.                 a task number in the control file.
  22514.  
  22515.              Local Input Timeout
  22516.  
  22517.                 This statement instructs Maximus to apply the input timeout
  22518.                 counter to local users in addition to remote users.
  22519.                 (Normally, the input timer is disabled for local logons,
  22520.                 meaning that that the SysOp can log on, go away for 30 min-
  22521.                 utes, and still have Maximus waiting at the input prompt.)
  22522.  
  22523.              Logon Level <priv>
  22524.              Logon Preregistered
  22525.  
  22526.                 This keyword specifies the privilege level to be assigned
  22527.                 to new users. If you use the Logon Preregistered statement
  22528.                 instead, new users will not be allowed to log on. (Maximus
  22529.                 will instead hang up after displaying the Uses Application
  22530.                 file.)
  22531.  
  22532.  
  22533.  
  22534.              18. Control File Reference                                410
  22535.  
  22536.              Logon TimeLimit <time>
  22537.  
  22538.                 This keyword specifies the maximum amount of time, in min-
  22539.                 utes, that the user is given to log on, read through the
  22540.                 Uses Application file, enter a password, and so on.
  22541.  
  22542.              Mailchecker Kill <priv>
  22543.              Mailchecker Reply <priv>
  22544.  
  22545.                 These keywords control the privilege level required to ac-
  22546.                 cess the Kill and Reply functions in the Msg_Browse command
  22547.                 and in the mailchecker.
  22548.  
  22549.                 The Mailchecker Kill keyword controls the privilege level
  22550.                 required to delete a message using the Browse command.
  22551.  
  22552.                 The Mailchecker Reply keyword controls the privilege level
  22553.                 required to reply to a message using the Browse command.
  22554.  
  22555.        Note!    When Maximus determines whether or not a user has access
  22556.                 to the Reply and Kill commands, it also examines the mes-
  22557.                 sage menu to find the privilege levels for the Msg_Reply,
  22558.                 Msg_Kill and Msg_Upload options.
  22559.  
  22560.                 For this feature to work properly, you must have a menu ex-
  22561.                 plicitly called "MESSAGE", and that menu must contain op-
  22562.                 tions for Msg_Reply, Msg_Kill and Msg_Upload (with privi-
  22563.                 lege levels that can be accessed by the user).
  22564.  
  22565.                 Even if you have renamed your main message menu to some-
  22566.                 thing else, you still need a menu called "MESSAGE". (Note
  22567.                 that this menu need not be reachable from your normal menu
  22568.                 structure. The sole purpose of this menu is to store the
  22569.                 privilege levels required to access the Reply and Kill com-
  22570.                 mands in the mailchecker.)
  22571.  
  22572.              MaxMsgSize <size>
  22573.  
  22574.                 This keyword controls the maximum size of messages uploaded
  22575.                 using the Msg_Upload menu option.
  22576.  
  22577.                 The value for MaxMsgSize does not apply to messages entered
  22578.                 locally, nor does it apply to users in a class with the
  22579.                 MailFlags MsgAttrAny flag.
  22580.  
  22581.              Menu Path <path>
  22582.  
  22583.                 This keyword tells Maximus where to find the default menu
  22584.                 (*.mnu) files
  22585.  
  22586.  
  22587.  
  22588.              18. Control File Reference                                411
  22589.  
  22590.              MessageData <file>
  22591.  
  22592.                 This keyword tells Maximus the root filename to use when
  22593.                 creating the message area data file. Maximus stores all in-
  22594.                 formation related to message areas in files named
  22595.                 <name>.dat and <name>.idx.
  22596.  
  22597.              Min Logon Baud <speed>
  22598.  
  22599.                 This keyword specifies the minimum speed at which a user
  22600.                 must call in order to log on to the system. See also the
  22601.                 LogonBaud keyword in the access control file.
  22602.  
  22603.              Min NonTTY Baud <speed>
  22604.  
  22605.                 This keyword specifies the minimum speed at which a user
  22606.                 must call in order to use a terminal mode other than TTY.
  22607.  
  22608.              Min RIP Baud <speed>
  22609.  
  22610.                 This keyword specifies the minimum speed at which a user
  22611.                 must call in order to use RIPscrip graphics. RIPscrip sup-
  22612.                 port can be disabled by setting this value higher than the
  22613.                 maximum baud rate.
  22614.  
  22615.                 A new user must be logged in at a speed that is at least
  22616.                 equal to or higher than the Min NonTTY Baud and Min RIP
  22617.                 Baud speeds in order to enable RIPscrip. Maximus attempts
  22618.                 to auto-detect RIPscrip capability on the remote and will
  22619.                 set the default response in the new user logon sequence ac-
  22620.                 cordingly.
  22621.  
  22622.              No RealName Kludge
  22623.  
  22624.                 This keyword instructs Maximus not to insert the
  22625.                 ^aREALNAME: line into messages entered in an anonymous mes-
  22626.                 sage area.
  22627.  
  22628.                 Normally, this line aids in tracking down users who try to
  22629.                 abuse the ability to leave anonymous messages. However,
  22630.                 there are circumstances when you want to ensure that a user
  22631.                 can leave messages which are completely confidential, and
  22632.                 enabling this keyword will do that. This option can be
  22633.                 overridden on an area-by-area basis; see the Style keyword
  22634.                 in the message area control file for more information.
  22635.  
  22636.              RIP Path <path>
  22637.  
  22638.                 This keyword tells Maximus where to find all of the default
  22639.                 *.rip and *.icn files to be sent using the [ripdisplay] and
  22640.                 [ripsend] MECCA tokens.
  22641.  
  22642.  
  22643.  
  22644.              18. Control File Reference                                412
  22645.  
  22646.                 This path can be changed at runtime using the [rippath]
  22647.                 MECCA token.
  22648.  
  22649.              Save Directories <drives>
  22650.  
  22651.          DOS    When Maximus runs an external program, this keyword in-
  22652.        only!    structs it to record the "current directory" for the
  22653.                 specified drives.
  22654.  
  22655.                 The <drives> parameter is a list of all drive letters on
  22656.                 your system, except for removable media (floppy drives and
  22657.                 CD-ROMs).
  22658.  
  22659.              Single Word Names
  22660.  
  22661.                 This keyword instructs Maximus to permit usernames that
  22662.                 contain only a single word. This option may be useful on
  22663.                 systems that support aliases. (Maximus will also suppress
  22664.                 the default "What is your LAST name:" prompt when this key-
  22665.                 word is enabled.)
  22666.  
  22667.              Stage Path <path>
  22668.  
  22669.                 This keyword tells Maximus to use <path> as a temporary di-
  22670.                 rectory for staging file transfers.
  22671.  
  22672.                 This path is only used when a file area is declared using
  22673.                 Type Staged or Type Hidden. In areas with this type, Maxi-
  22674.                 mus will copy the files from the CD-ROM to the specified
  22675.                 staging directory before sending the files. This reduces
  22676.                 wear and tear on normal CD-ROMs, and it prevents thrashing
  22677.                 for multi-disk CD changers.
  22678.  
  22679.                 The declared path should always have at least as much space
  22680.                 as allowed for in your daily download limits. (If Maximus
  22681.                 is unable to copy a file to the staging area, the transfer
  22682.                 will send the file from its original location.)
  22683.  
  22684.              StatusLine
  22685.  
  22686.                 This keyword instructs Maximus to display a status line at
  22687.                 the bottom of the screen. The status line is only active
  22688.                 for remote users.
  22689.  
  22690.              Strict Time Limit
  22691.  
  22692.                 This keyword instructs Maximus to terminate callers who run
  22693.                 over their time limits while in the middle of a download.
  22694.                 If this happens, Maximus will create a log entry and abort
  22695.                 the file transfer. This feature only works for internal
  22696.                 protocols.
  22697.  
  22698.  
  22699.  
  22700.              18. Control File Reference                                413
  22701.  
  22702.              Track Base <root>
  22703.  
  22704.                 This keyword specifies the path and root filename of the
  22705.                 MTS database. This keyword should only specify the path and
  22706.                 up to four letters for the root of the database name.
  22707.  
  22708.                 For example, assuming the following line:
  22709.  
  22710.                 Track Base c:\max\trk
  22711.  
  22712.                 Maximus will create the following database files:
  22713.  
  22714.                 c:\max\trkmsg.db
  22715.                 c:\max\trkmsg.i00
  22716.                 c:\max\trkmsg.i01
  22717.                 c:\max\trkmsg.i02
  22718.                 c:\msg\trkarea.i00
  22719.                 c:\msg\trkown.i00
  22720.  
  22721.              Track Exclude <filespec>
  22722.  
  22723.                 This keyword gives the name of the "exclusion list" for
  22724.                 controlling automatic message assignment in MTS areas.
  22725.  
  22726.                 In some situations, a MTS moderator may not wish to track
  22727.                 messages that are entered by certain users. The exclusion
  22728.                 list is a flat text file, one name per line, which lists
  22729.                 the names of all users to be excluded from the tracking
  22730.                 system.
  22731.  
  22732.                 Messages entered by these users can be manually placed in
  22733.                 the tracking system using the Track/Insert command.
  22734.  
  22735.              Track Modify <priv>
  22736.  
  22737.                 This keyword controls the privilege level required to mod-
  22738.                 ify tracking information for messages which are not owned
  22739.                 by the user performing the modification. (In this case,
  22740.                 "owned" refers to the user in the "owner" field of that
  22741.                 message in the MTS database.)
  22742.  
  22743.                 This privilege level is also required to delete messages
  22744.                 from the tracking database and to access the Track/Admin
  22745.                 menu.
  22746.  
  22747.              Track View <priv>
  22748.  
  22749.                 This keyword controls the privilege level required to view
  22750.                 tracking information of messages owned by others. To view
  22751.                 tracking information in a message, that message must either
  22752.                 be owned by the current user, or that user must have a
  22753.                 privilege level of at least the value specified by this
  22754.                 keyword.
  22755.  
  22756.  
  22757.  
  22758.              18. Control File Reference                                414
  22759.  
  22760.              Upload Check Dupe
  22761.              Upload Check Dupe Extension
  22762.  
  22763.                 These keywords instruct Maximus to check for duplicate
  22764.                 files when processing uploads.
  22765.  
  22766.                 The Upload Check Dupe keyword tells Maximus to compare only
  22767.                 the root part of the filename. Using this method, "foo.zip"
  22768.                 and "foo.lzh" will be considered duplicates.
  22769.  
  22770.                 The Upload Check Dupe Extension keyword tells Maximus to
  22771.                 compare the full filename and extension of the uploaded
  22772.                 file.
  22773.  
  22774.                 To use this feature, you must use the FB utility to create
  22775.                 a file database.
  22776.  
  22777.              Upload Check Virus <batchfile>
  22778.  
  22779.                 This keyword instructs Maximus to call a batch or command
  22780.                 file every time a file is uploaded.
  22781.  
  22782.                 <batchfile> specifies the name of the batch file to run.
  22783.                 For example:
  22784.  
  22785.                 Upload Check Virus   vircheck.bat
  22786.  
  22787.                 (For OS/2, use vircheck.cmd.)
  22788.  
  22789.                 This keyword tells Maximus to call vircheck.bat every time
  22790.                 a file is uploaded. Maximus will call the batch file using
  22791.                 the following format:
  22792.  
  22793.                 vircheck.bat path name extension miscdir task
  22794.  
  22795.                 path is the path of the uploaded file (including the trail-
  22796.                 ing backslash).
  22797.  
  22798.                 name is the root name of the file (without the extension).
  22799.  
  22800.                 extension is the extension of the file, beginning with a
  22801.                 period (".").
  22802.  
  22803.                 miscdir is the path to the Maximus \max\misc directory.
  22804.  
  22805.                 task is the current node number.
  22806.  
  22807.                 Please note that the file name and extension are passed as
  22808.                 two separate arguments. This allows the batch file to eas-
  22809.                 ily check for uploads with a certain extension.
  22810.  
  22811.                 The batch file can process the uploads as desired, includ-
  22812.                 ing scanning for viruses, refusing files with bad exten-
  22813.  
  22814.  
  22815.  
  22816.              18. Control File Reference                                415
  22817.  
  22818.                 sions, and so on. After the batch file returns, Maximus
  22819.                 will check again to see if the uploaded file still exists.
  22820.  
  22821.                 If the file still exists, Maximus displays
  22822.                 \max\misc\file_ok.bbs. Normally, this file contains a mes-
  22823.                 sage informing the user that the file contained no viruses.
  22824.                 Maximus will then ask for an upload description and credit
  22825.                 the user's account.
  22826.  
  22827.                 If the uploaded file no longer exists, presumably because
  22828.                 it was removed by vircheck.bat, Maximus will display
  22829.                 \max\misc\file_bad.bbs. This file presumably mentions that
  22830.                 the virus check failed.
  22831.  
  22832.                 This feature was designed for automated virus-checking pro-
  22833.                 grams, but other tricks can also be done with batch files.
  22834.                 The uploaded file's extension can be tested as a separate
  22835.                 argument, so it can be used to block uploads of files with
  22836.                 certain extensions.
  22837.  
  22838.                 The \max\misc\file_bad.bbs file can also be swapped by
  22839.                 vircheck.bat for another file, so a different file can be
  22840.                 displayed for virus checks and archive corruption checks.
  22841.                 The display file could also be used to display the log of
  22842.                 the virus checking program, thereby giving the user more
  22843.                 information about the virus itself.
  22844.  
  22845.              Upload Log <log_name>
  22846.  
  22847.                 This keyword specifies the name of a log file used for
  22848.                 storing the names of uploaded files.
  22849.  
  22850.                 One line is written to this file for every upload received.
  22851.                 Included is the name of the file uploaded, the name of the
  22852.                 user who uploaded it, the size of the file, and the current
  22853.                 date and time. This makes it very easy to keep track of
  22854.                 which user uploaded which file.
  22855.  
  22856.              Upload Space Free <amount>
  22857.  
  22858.                 This keyword tells Maximus to prevent users from uploading
  22859.                 files if there are less than <amount> free kilobytes of
  22860.                 space on the upload drive. (If there is less than <amount>
  22861.                 kilobytes available, Maximus displays the Uses NoSpace file
  22862.                 and refuses the upload.)
  22863.  
  22864.              Uses Application <filespec>
  22865.  
  22866.                 This file is displayed to a new user after answering Y to
  22867.                 the "Firstname Lastname [Y,n]?" prompt, but before prompt-
  22868.                 ing the user for city and phone number information.
  22869.  
  22870.  
  22871.  
  22872.              18. Control File Reference                                416
  22873.  
  22874.              Uses BOREDhelp <filespec>
  22875.  
  22876.                 This file is displayed to first-time callers who enter the
  22877.                 BORED editor when their help level is set to novice.
  22878.  
  22879.              Uses BadLogon <filespec>
  22880.  
  22881.                 This file is displayed to users who failed the last log-on
  22882.                 attempt due to an invalid password.
  22883.  
  22884.              Uses Barricade <filespec>
  22885.  
  22886.                 This file is displayed to users after they enter a barri-
  22887.                 caded message or file area, but before they are prompted
  22888.                 for the password.
  22889.  
  22890.              Uses BeginChat <filespec>
  22891.  
  22892.                 This file is displayed to the user when the SysOp enters
  22893.                 CHAT mode. This is a good place to put something like, "Hi
  22894.                 [user], this is the SysOp speaking."
  22895.  
  22896.                 The default Uses BeginChat message is "CHAT: start".
  22897.  
  22898.              Uses ByeBye <filespec>
  22899.  
  22900.                 This file is displayed to users after they select the Good-
  22901.                 bye menu option.
  22902.  
  22903.              Uses Cant_Enter_Area <filespec>
  22904.  
  22905.                 This file is displayed to users when they try select an
  22906.                 area that does not exist. The default response is "That
  22907.                 area does not exist!"
  22908.  
  22909.              Uses Configure <filename>
  22910.  
  22911.                 This file is displayed to new users after they log in, but
  22912.                 before the standard user configuration questions are asked.
  22913.  
  22914.                 If the "configured" bit is set in the user record after
  22915.                 this file is displayed (via a MEX script, for example), the
  22916.                 standard configuration questions are skipped, thereby al-
  22917.                 lowing the standard new user configuration to be replaced.
  22918.  
  22919.              Uses ContentsHelp <filespec>
  22920.  
  22921.                 This file is displayed to users who request help for the
  22922.                 File_Contents command.
  22923.  
  22924.  
  22925.  
  22926.              18. Control File Reference                                417
  22927.  
  22928.              Uses DayLimit <filespec>
  22929.  
  22930.                 This file is displayed to users who try to log on after
  22931.                 having overrun their daily time limits.
  22932.  
  22933.              Uses EndChat <filespec>
  22934.  
  22935.                 This file is displayed to the user when the SysOp exits
  22936.                 chat mode. The default response is "END CHAT."
  22937.  
  22938.              Uses EntryHelp <file>
  22939.  
  22940.                 This file is displayed to the user just before entering the
  22941.                 message editor, regardless of whether the user is using the
  22942.                 full screen editor or the line editor. This file can offer
  22943.                 additional help or set up the screen display for RIPscrip
  22944.                 callers.
  22945.  
  22946.              Uses FileAreas <filespec>
  22947.  
  22948.                 This file is displayed to a user when a file area listing
  22949.                 is requested. This display file replaces the automatically-
  22950.                 generated file area list.
  22951.  
  22952.              Uses Filename_Format <filespec>
  22953.  
  22954.                 This file is displayed to users who try to upload files us-
  22955.                 ing an invalid filename.
  22956.  
  22957.              Uses HeaderHelp <file>
  22958.  
  22959.                 This file is displayed to users just before the message
  22960.                 header entry screen is displayed. This file can contain in-
  22961.                 formation regarding message attributes, using aliases,
  22962.                 anonymous areas, and so on.
  22963.  
  22964.              Uses Leaving <filespec>
  22965.  
  22966.                 This file is displayed just before Maximus exits to run an
  22967.                 external program from a menu option.
  22968.  
  22969.              Uses LocateHelp <filespec>
  22970.  
  22971.                 This file is displayed to users who request help using the
  22972.                 File_Locate command.
  22973.  
  22974.              Uses Logo <filespec>
  22975.  
  22976.                 This file (normally called \max\misc\logo.bbs) is displayed
  22977.                 immediately after Maximus connects with the user. This file
  22978.                 should normally contain a small amount of information de-
  22979.                 scribing your BBS. This file must not contain ANSI or AVA-
  22980.                 TAR graphics.
  22981.  
  22982.  
  22983.  
  22984.              18. Control File Reference                                418
  22985.  
  22986.              Uses MaxEdHelp <filespec>
  22987.  
  22988.                 This file is displayed to users who ask for help (by press-
  22989.                 ing "^k?") from within the MaxEd editor.
  22990.  
  22991.              Uses MsgAreas <filespec>
  22992.  
  22993.                 This file is displayed to a user when a file area listing
  22994.                 is requested. If present, this file replaces the automati-
  22995.                 cally-generated file area list.
  22996.  
  22997.              Uses NewUser1 <filespec>
  22998.  
  22999.                 This file is displayed to a new user right before Maximus
  23000.                 asks the user to enter a password.
  23001.  
  23002.              Uses NewUser2 <filespec>
  23003.  
  23004.                 This file is displayed to a new user in lieu of the Uses
  23005.                 Welcome file.
  23006.  
  23007.              Uses NoMail <filespec>
  23008.  
  23009.                 This file is displayed to a user after the [msg_checkmail]
  23010.                 MECCA token determines that there is no mail waiting for
  23011.                 the user.
  23012.  
  23013.              Uses NoSpace <filespec>
  23014.  
  23015.                 This file is displayed when the amount of space free on the
  23016.                 upload drive is less than the value specified by the Upload
  23017.                 Space Free keyword.
  23018.  
  23019.              Uses NotFound <filespec>
  23020.  
  23021.                 This file is displayed to a new user after the user's name
  23022.                 is entered, but before the "First Last [Y,n]?" prompt is
  23023.                 displayed.
  23024.  
  23025.              Uses ProtocolDump <filespec>
  23026.  
  23027.                 This file is displayed to the user instead of the standard
  23028.                 "canned" list of protocol names. This file is displayed for
  23029.                 both the File_Upload and File_Download menu options.
  23030.  
  23031.              Uses Quote <filespec>
  23032.  
  23033.                 This keyword specifies the name of an ASCII text file that
  23034.                 contain quotes and random pieces of wisdom. Each quote in
  23035.                 the file should be separated by a single blank line. This
  23036.                 file can be accessed using the MECCA [quote] token.
  23037.  
  23038.  
  23039.  
  23040.              18. Control File Reference                                419
  23041.  
  23042.              Uses ReplaceHelp <filespec>
  23043.  
  23044.                 This file is displayed to the user just after selecting the
  23045.                 Edit_Edit option on the editor menu. This file describes
  23046.                 the search and replace feature of the line editor.
  23047.  
  23048.              Uses Returning <filespec>
  23049.  
  23050.                 This file is displayed to the user upon returning from an
  23051.                 external program invoked by a menu option.
  23052.  
  23053.              Uses Rookie <filespec>
  23054.  
  23055.                 This file is displayed to a user who has called between two
  23056.                 and eight times, in lieu of the Uses Welcome file.
  23057.  
  23058.              Uses Shell_Leaving <filespec>
  23059.  
  23060.                 This file is displayed to the user immediately after the
  23061.                 SysOp presses <alt-j> on the local console to shell to the
  23062.                 operating system.
  23063.  
  23064.              Uses Shell_Returning <filespec>
  23065.  
  23066.                 This file is displayed to the user after the SysOp returns
  23067.                 from a shell.
  23068.  
  23069.              Uses TimeWarn <filespec>
  23070.  
  23071.                 This file is displayed to the user just before displaying
  23072.                 the main menu, as long as that user has made more than one
  23073.                 call on the current day.
  23074.  
  23075.              Uses TooSlow <filespec>
  23076.  
  23077.                 This file is displayed to users whose speed is lower than
  23078.                 the minimum speed required in Min Logon Baud, or if the
  23079.                 user's speed is less than the LogonBaud keyword for the
  23080.                 user's class in the access control file.
  23081.  
  23082.              Uses Tunes <filespec>
  23083.  
  23084.                 This keyword specifies the name and location of the Maximus
  23085.                 tunes file. This tune file can be used to play simple melo-
  23086.                 dies on the PC speaker when a user yells. For more informa-
  23087.                 tion on the format of this file, please see the comments in
  23088.                 the distribution version of tunes.bbs.
  23089.  
  23090.              Uses Welcome <filespec>
  23091.  
  23092.                 This file is displayed to normal users who have called more
  23093.                 than eight times. This file is displayed immediately after
  23094.                 the user enters the log-on password.
  23095.  
  23096.  
  23097.  
  23098.              18. Control File Reference                                420
  23099.  
  23100.              Uses XferBaud <filespec>
  23101.  
  23102.                 This file is displayed to users whose speed is less than
  23103.                 the speed required for the XferBaud setting for their user
  23104.                 class in the access control file.
  23105.  
  23106.              Use UMSGIDs
  23107.  
  23108.                 This keyword instructs Maximus to use unique message iden-
  23109.                 tifiers when displaying messages in Squish areas.
  23110.  
  23111.                 This means that every message entered in a Squish area will
  23112.                 have a unique message number assigned to it. This number
  23113.                 will never be reused, regardless of message deletions. This
  23114.                 feature only works for Squish-style bases, so this keyword
  23115.                 has no impact on *.MSG areas.
  23116.  
  23117.              Yell Off
  23118.  
  23119.                 This keyword completely disables the Yell function.
  23120.  
  23121.  
  23122.              18.3. Language Control File
  23123.  
  23124.  
  23125.              18.3.1. Description
  23126.  
  23127.              The default language control file is called language.ctl.
  23128.              This file defines the languages supported in Maximus's multi-
  23129.              lingual system. This file also allows the SysOp to select a
  23130.              default language by placing the Language keywords in a par-
  23131.              ticular order.
  23132.  
  23133.  
  23134.              18.3.2. Language Section Keyword Listing
  23135.  
  23136.              Language <filename>
  23137.  
  23138.                 This keyword specifies the name of a Maximus-specific lan-
  23139.                 guage file. For example, the statement "Language English"
  23140.                 tells Maximus to look for a file called english.ltf in the
  23141.                 Path Language directory.
  23142.  
  23143.                 Up to eight language files may be specified in this sec-
  23144.                 tion. Under DOS, remember that language filenames must not
  23145.                 be more than eight characters long.
  23146.  
  23147.                 The first language listed in this section is used as the
  23148.                 default for both new users and the SysOp's log file.
  23149.  
  23150.  
  23151.  
  23152.              18. Control File Reference                                421
  23153.  
  23154.              18.4. Off-Line Reader Control File
  23155.  
  23156.  
  23157.              18.4.1. Description
  23158.  
  23159.              The default off-line reader control file is reader.ctl. If
  23160.              you do not wish to enable the off-line reader, the Include
  23161.              Reader.Ctl statement in max.ctl may be commented out.
  23162.  
  23163.  
  23164.              18.4.2. Reader Section Keyword Listing
  23165.  
  23166.              Archivers <filespec>
  23167.  
  23168.                 This keyword specifies the file that contains definitions
  23169.                 for external compression utilities. The file is identical
  23170.                 in format to the format of the compress.cfg file used by
  23171.                 the Squish mail processor. If you are running both Maximus
  23172.                 and Squish, this keyword can point to the same compression
  23173.                 file as used by Squish.
  23174.  
  23175.              Packet Name <filename>
  23176.  
  23177.                 This keyword defines an eight-character identifier for your
  23178.                 system. Maximus uses this identifier when building QWK
  23179.                 packets. Downloaded packets will be called <filename>.qwk,
  23180.                 and uploaded replies will be called <filename>.rep.
  23181.  
  23182.                 This keyword should normally specify an abbreviation of
  23183.                 your BBS name. The abbreviation must be eight characters or
  23184.                 less and cannot include spaces. Only valid DOS filename
  23185.                 characters are permitted. (A-Z, 0-9, and !@#$%&()_.)
  23186.  
  23187.              Work Directory <path>
  23188.  
  23189.                 This keyword specifies the name of the directory used for
  23190.                 creating QWK packets. Maximus creates subdirectories under
  23191.                 the path you specify for per-node storage.
  23192.  
  23193.                 However, any files contained in the main work directory (as
  23194.                 specified by <path>) are included in all downloaded QWK
  23195.                 packets.
  23196.  
  23197.              Max Messages <num>
  23198.  
  23199.                 This keyword defines the maximum number of messages that
  23200.                 Maximus will pack into one QWK packet. If you do not wish
  23201.                 to limit the number of messages, specify Max Messages 0.
  23202.  
  23203.              Phone Number <phone number>
  23204.  
  23205.                 This keyword defines the phone number of your BBS, as it
  23206.                 should be shown in downloaded QWK mail packets. The number
  23207.  
  23208.  
  23209.  
  23210.              18. Control File Reference                                422
  23211.  
  23212.                 should be in the "(xxx) yyy-zzzz" format, since some off-
  23213.                 line readers depend on the phone number looking like this.
  23214.                 However, Maximus itself does not care about the format, so
  23215.                 it will copy the string verbatim to the control.dat file in
  23216.                 the QWK packet.
  23217.  
  23218.  
  23219.              18.5. Colors Control File
  23220.  
  23221.  
  23222.              18.5.1. Description
  23223.  
  23224.              The default colors control file is colors.ctl. Maximus uses
  23225.              this file to select colors for certain Maximus prompts.
  23226.  
  23227.              This control file contains only those colors which are shown
  23228.              to the SysOp. A large number of other colors are stored in
  23229.              the \max\lang\colors.lh language include file. Please see the
  23230.              comments inside that file for more information.
  23231.  
  23232.  
  23233.              18.5.2. Colors Section Keyword Listing
  23234.  
  23235.              Popup Border <color>
  23236.  
  23237.                 Color for the border of a pop-up window. The default color
  23238.                 is yellow on blue.
  23239.  
  23240.              Popup Highlight <color>
  23241.  
  23242.                 Color for highlighted text inside pop-up windows. The de-
  23243.                 fault color is yellow on blue.
  23244.  
  23245.              Popup LSelect <color>
  23246.  
  23247.                 Color for selected items on pop-up pick lists. The default
  23248.                 color is grey on red.
  23249.  
  23250.              Popup List <color>
  23251.  
  23252.                 Color for standard items on pop-up pick lists. The default
  23253.                 color is black on grey.
  23254.  
  23255.              Popup Text <color>
  23256.  
  23257.                 Color for the text in a pop-up window. The default color is
  23258.                 white on blue.
  23259.  
  23260.              Status Bar <color>
  23261.  
  23262.                 Color for the main status bar. The default color is black
  23263.                 on white.
  23264.  
  23265.  
  23266.  
  23267.              18. Control File Reference                                423
  23268.  
  23269.              Status Chat <color>
  23270.  
  23271.                 Color for the chat request indicator ("C"). The default
  23272.                 color is blinking black on white.
  23273.  
  23274.              Status Key <color>
  23275.  
  23276.                 Color for the rest of the status-line key flags, such as K.
  23277.                 The default color is black on white.
  23278.  
  23279.              WFC Activity <color>
  23280.  
  23281.                 Color for the activity window on the "Waiting for Caller"
  23282.                 screen. The default color is white on blue.
  23283.  
  23284.              WFC ActivityBor <color>
  23285.  
  23286.                 Color for the activity window border on the "Waiting for
  23287.                 Caller" screen. The default color is lightcyan on blue.
  23288.  
  23289.              WFC Keys <color>
  23290.  
  23291.                 Color for the keys window on the "Waiting for Caller"
  23292.                 screen. The default color is yellow on blue.
  23293.  
  23294.              WFC KeysBor <color>
  23295.  
  23296.                 Color for the keys window border on the "Waiting for
  23297.                 Caller" screen. The default color is white on blue.
  23298.  
  23299.              WFC Modem <color>
  23300.  
  23301.                 Color for the modem window on the "Waiting for Caller"
  23302.                 screen. The default color is gray on blue.
  23303.  
  23304.              WFC ModemBor <color>
  23305.  
  23306.                 Color for the modem window border on the "Waiting for
  23307.                 Caller" screen. The default color is lightgreen on blue.
  23308.  
  23309.              WFC Line <color>
  23310.  
  23311.                 Color for the bar at the top of the "Waiting for Caller"
  23312.                 screen. The default color is white.
  23313.  
  23314.              WFC Name <color>
  23315.  
  23316.                 Color for the Maximus name on the "Waiting for Caller"
  23317.                 screen. The default color is yellow.
  23318.  
  23319.  
  23320.  
  23321.              18. Control File Reference                                424
  23322.  
  23323.              WFC Status <color>
  23324.  
  23325.                 Color for the status window on the "Waiting for Caller"
  23326.                 screen. The default color is white on blue.
  23327.  
  23328.              WFC StatusBor <color>
  23329.  
  23330.                 Color for the status window border on the "Waiting for
  23331.                 Caller" screen. The default color is yellow on blue.
  23332.  
  23333.  
  23334.              18.6. Message Area Control File
  23335.  
  23336.  
  23337.              18.6.1 Description
  23338.  
  23339.              The default message area control file is called msgarea.ctl.
  23340.              This file defines all of the message areas available on a
  23341.              Maximus system.
  23342.  
  23343.              Every message area must begin with a MsgArea keyword, and
  23344.              every message area must end with a End MsgArea keyword.
  23345.  
  23346.  
  23347.              18.6.2. Alphabetical Keyword Listing
  23348.  
  23349.              ACS
  23350.  
  23351.                 This keyword specifies the access level required to see or
  23352.                 access this message area.
  23353.  
  23354.              AttachPath <path>
  23355.  
  23356.                 This keyword specifies the path to use for storing local
  23357.                 file attaches that are created in this message area.
  23358.  
  23359.                 <path> should point to an empty directory that Maximus can
  23360.                 use for storing the file attaches.
  23361.  
  23362.              Barricade <menu_name> <barricade_file>
  23363.  
  23364.                 This keyword specifies a barricade file to be used for the
  23365.                 current message area. As long as the current menu is
  23366.                 <menu_name>, the barricade privilege level from
  23367.                 <barricade_file> will override the user's normal privilege
  23368.                 level. Please see section 4.6 for more information on bar-
  23369.                 ricade files.
  23370.  
  23371.              Desc <desc>
  23372.              Description <desc>
  23373.  
  23374.                 These keywords specify the description of the message area,
  23375.                 as you wish it to appear on the message area menu.
  23376.  
  23377.  
  23378.  
  23379.              18. Control File Reference                                425
  23380.  
  23381.              End MsgArea
  23382.  
  23383.                 This keyword tells SILT that the message area definition is
  23384.                 complete.
  23385.  
  23386.              MenuName <orig_menu> <replace_menu>
  23387.  
  23388.                 While Maximus is in this message area, when it is in-
  23389.                 structed to display the menu <orig_menu>, it will instead
  23390.                 display <replace_menu>.
  23391.  
  23392.              MsgArea <area>
  23393.  
  23394.                 This keyword tells SILT to begin a message area definition.
  23395.                 <area> is the "leaf" name of the message area; if the area
  23396.                 is contained within a message division, the name of the di-
  23397.                 vision will be added to the front of the string when writ-
  23398.                 ing the area to the message area data file.
  23399.  
  23400.              MsgDivisionBegin <name> <acs> <display_file> <desc>
  23401.  
  23402.                 This keyword is used to begin a message area division. Di-
  23403.                 visions can be used to create a multi-level, hierarchical
  23404.                 message area structure.
  23405.  
  23406.                 <name> is the name of the message area division. This
  23407.                 should be a very short tag identifying the area type. (It
  23408.                 should be short because it is added to the beginning of all
  23409.                 area names declared within the division.)
  23410.  
  23411.                 <acs> is the access control string required to view the
  23412.                 message division. Please note that the ACS specified for
  23413.                 this division has nothing to do with the ACS required to
  23414.                 enter a contained message area. (However, the ACS for the
  23415.                 message areas in the division will typically be at least as
  23416.                 restrictive as the ACS for the division.)
  23417.  
  23418.                 <display_file> is the name of the message area display file
  23419.                 to show when the user requests an area list of this divi-
  23420.                 sion. This file is only used if the corresponding Uses
  23421.                 MsgAreas statement is enabled in the system control file.
  23422.                 If you are not using custom message area menus, specify a
  23423.                 "." as the filename.
  23424.  
  23425.                 <desc> is the description for this division, as it will ap-
  23426.                 pear on the message area menu.
  23427.  
  23428.              MsgDivisionEnd
  23429.  
  23430.                 This keyword ends a message division.
  23431.  
  23432.  
  23433.  
  23434.              18. Control File Reference                                426
  23435.  
  23436.              Origin <primary_addr> <seenby_addr> [text]
  23437.  
  23438.                 For an EchoMail area, this keyword instructs Maximus to use
  23439.                 an origin line other than the default origin in the system
  23440.                 control file.
  23441.  
  23442.                 <primary_addr> is the address to place in the MSGID kludge
  23443.                 line at the top of the message. This address is also placed
  23444.                 on the origin line.
  23445.  
  23446.                 <seenby_addr> is the address to use in the SEEN-BY line.
  23447.  
  23448.                 A period (".") can be specified for either or both of
  23449.                 <primary_addr> and <seenby_addr> to use the default ad-
  23450.                 dress.
  23451.  
  23452.                 The optional [text] contains the new text to use on the
  23453.                 origin line. If [text] is omitted, Maximus uses the default
  23454.                 origin line text.
  23455.  
  23456.                 For example:
  23457.  
  23458.                 Origin . . New origin for this area
  23459.  
  23460.                 This statement simply changes the origin text.
  23461.  
  23462.                 Origin 1:249/106.4 1:24906/2 New point text
  23463.  
  23464.                 This statement changes the primary address to 1:249/106.4,
  23465.                 changes the SEEN-BY address to 1:24906/2, and changes the
  23466.                 origin line text to "New point text".
  23467.  
  23468.              Override <menu_name> <option_type> <acs> [letter]
  23469.  
  23470.                 The Override keyword instructs Maximus to alter the privi-
  23471.                 lege level required to access a menu option while the user
  23472.                 is in this message area.
  23473.  
  23474.                 <menu_name> is the name of the menu containing the command
  23475.                 to be overridden. In most cases, this will be "MESSAGE".
  23476.  
  23477.                 <option_type> is the menu option type to override. Any of
  23478.                 the keywords from the menu control file can be used here.
  23479.                 If you do not specify a [letter], the override will apply
  23480.                 to all options on the menu with a type of <option_type>.
  23481.  
  23482.                 <acs> is the new ACS required to access the menu option.
  23483.  
  23484.                 [letter] is the optional first letter of the command to be
  23485.                 overridden. If this letter is specified, the override will
  23486.                 only apply to menu commands which: are on the menu called
  23487.                 <menu_name>, which have an option type of <option_type> and
  23488.                 which have a first letter of [letter].
  23489.  
  23490.  
  23491.  
  23492.              18. Control File Reference                                427
  23493.  
  23494.                 For example:
  23495.  
  23496.                 Override MESSAGE Msg_Reply SysOp/135 R
  23497.  
  23498.                 This command overrides the Reply option on the message
  23499.                 menu. In the area where this definition is placed, a user
  23500.                 must pass the ACS test of "SysOp/135" before being allowed
  23501.                 to reply to a message in this area. The override is further
  23502.                 restricted so that it only applies to commands that start
  23503.                 with the letter "R". (Had there been other Msg_Reply op-
  23504.                 tions on the menu that started with other letters, they
  23505.                 would not be overridden.)
  23506.  
  23507.              Owner <id>
  23508.  
  23509.                 This keyword sets a default MTS owner for this message
  23510.                 area. The Owner keyword must be specified in every area
  23511.                 that uses the Style Audit style. This owner/area link can
  23512.                 also be modified using the Track/Admin/Owner menu.
  23513.  
  23514.              Path <path>
  23515.  
  23516.                 This keyword tells Maximus where to find the files that
  23517.                 store the data in this message area.
  23518.  
  23519.                 If the area uses the Squish format (default), <path> must
  23520.                 specify the directory and root filename of the message
  23521.                 files.
  23522.  
  23523.                 If this area uses the *.MSG format, <path> must specify the
  23524.                 name of the directory used for storing the message files.
  23525.                 All *.MSG areas must have a separate directory of their
  23526.                 own; two *.MSG areas cannot be stored in the same direc-
  23527.                 tory.
  23528.  
  23529.              Renum Days <num>
  23530.  
  23531.                 This keyword tells Maximus to keep no more than <num> days
  23532.                 worth of messages in this area.
  23533.  
  23534.                 For *.MSG areas, messages are purged by the MR renumbering
  23535.                 program.
  23536.  
  23537.                 For Squish areas, messages are purged using the SQPACK
  23538.                 utility. (SQPACK is available as part of the Squish pro-
  23539.                 gram.)
  23540.  
  23541.                 If you are using the Squish mail processor, you only need
  23542.                 to set the renumbering option in one place ---either in
  23543.                 your message area control file or in your squish.cfg file.
  23544.  
  23545.  
  23546.  
  23547.              18. Control File Reference                                428
  23548.  
  23549.              Renum Max <num>
  23550.  
  23551.                 This keyword tells Maximus to store no more than <num> mes-
  23552.                 sages in the area at one time. For Squish-format areas,
  23553.                 Maximus will automatically purge messages as new messages
  23554.                 are added. For *.MSG-format areas, the external MR utility
  23555.                 must be run to purge messages.
  23556.  
  23557.                 If you are using the Squish mail processor, you only need
  23558.                 to set the renumbering option in one place ---either in
  23559.                 your message area control file or in your squish.cfg file.
  23560.  
  23561.              Style <styles>
  23562.  
  23563.                 This keyword sets an optional number of style flags for the
  23564.                 current area. The style describes the types of messages
  23565.                 that can be created, the physical message storage format,
  23566.                 and various other options.
  23567.  
  23568.                 <styles> can be zero or more of the options from Table
  23569.                 18.10:
  23570.  
  23571.                 Table 18.10 Message Area Styles
  23572.  
  23573.                 Style            Description
  23574.  
  23575.                 *.MSG            Store the message area using the *.MSG
  23576.                                  message format. (The default is to store
  23577.                                  the area using Squish format.)
  23578.                 Alias            Use the user's alias in the message
  23579.                                  header, rather than the user's real name.
  23580.                 Anon             Allow anonymous messages. Users are al-
  23581.                                  lowed to modify the "From:" field of the
  23582.                                  message to change it to a name of their
  23583.                                  choosing. However, Maximus will still in-
  23584.                                  sert a kludge line in the message contain-
  23585.                                  ing the user's real name. See the NoNameK-
  23586.                                  ludge style for information on disabling
  23587.                                  this feature.
  23588.                 Attach           Enable local file attaches in this area.
  23589.                                  This style must be used in conjunction
  23590.                                  with Style Squish. Please see section 5.2
  23591.                                  for more information.
  23592.                 Audit            Enable MTS tracking for this area. You
  23593.                                  also need to define the Owner keyword in
  23594.                                  this area to use the MTS feature. This
  23595.                                  style must also be used in conjunction
  23596.                                  with Style Squish. Please see section 5.6
  23597.                                  for more information on the Message Track-
  23598.                                  ing System.
  23599.                 Conf             This area is a conference area. Conference
  23600.                                  areas are similar to EchoMail areas, but
  23601.                                  conferences use PIDs and have no tear
  23602.  
  23603.  
  23604.  
  23605.              18. Control File Reference                                429
  23606.  
  23607.                                  lines. This style cannot be used in con-
  23608.                                  junction with the Net, Local or Echo
  23609.                                  styles.
  23610.                 Echo             This area is an EchoMail area. This style
  23611.                                  cannot be used in conjunction with the
  23612.                                  Conf, Net or Local styles.
  23613.                 HiBit            Allow 8-bit IBM extended ASCII characters
  23614.                                  in messages entered in this area.
  23615.                 Hidden           This area should not be shown on the stan-
  23616.                                  dard message area list. The Msg_Area prior
  23617.                                  and next commands will skip this area.
  23618.                                  However, the area can still be accessed by
  23619.                                  name.
  23620.                 Loc or Local     This is a local message area. This style
  23621.                                  cannot be used in conjunction with the
  23622.                                  Conf, Net, or Echo styles.
  23623.                 Net              This is a NetMail area. This style cannot
  23624.                                  be used in conjunction with Conf, Local or
  23625.                                  Echo styles.
  23626.                 NoMailCheck      This area is skipped during the standard
  23627.                                  mail-checking routine. This style is use-
  23628.                                  ful for areas which never contain personal
  23629.                                  mail for users.
  23630.                 NoNameKludge     This style toggles the No RealName Kludge
  23631.                                  setting in the system control file. This
  23632.                                  style is useful for preserving true ano-
  23633.                                  nymity in areas that accept "anonymous"
  23634.                                  messages.
  23635.                 Pub              Allow public messages in this area. If
  23636.                                  this flag is used in conjunction with
  23637.                                  Style Pvt, both public and private mes-
  23638.                                  sages are allowed. If neither flag is
  23639.                                  specified, this area allows only public
  23640.                                  messages.
  23641.                 Pvt              Allow private messages in this area. If
  23642.                                  this flag is used in conjunction with
  23643.                                  Style Pub, both public and private mes-
  23644.                                  sages are allowed. If neither flag is
  23645.                                  specified, this area allows only public
  23646.                                  messages.
  23647.                 ReadOnly         Only users in a class with MailFlags
  23648.                                  WriteRdOnly are allowed to write messages
  23649.                                  in this area.
  23650.                 RealName         Force the use of the user's real name when
  23651.                                  creating messages in this area.
  23652.                 Squish           The current area uses the Squish message
  23653.                                  format. This is the default.
  23654.  
  23655.  
  23656.              Tag
  23657.  
  23658.                 This keyword tells Maximus the name of the "area tag" for
  23659.                 the current message area. This tag is used when writing the
  23660.  
  23661.  
  23662.  
  23663.              18. Control File Reference                                430
  23664.  
  23665.                 Log EchoMail file. This tag should be the same as specified
  23666.                 for the area in your EchoMail processor's area control file
  23667.                 (typically areas.bbs or squish.cfg).
  23668.  
  23669.  
  23670.              18.7. File Area Control File
  23671.  
  23672.  
  23673.              18.7.1. Description
  23674.  
  23675.              The default file area control file is called filearea.ctl.
  23676.              This file defines all of the file areas accessible on a Maxi-
  23677.              mus system.
  23678.  
  23679.  
  23680.              18.7.2. Alphabetical Keyword Listing
  23681.  
  23682.              ACS <acs>
  23683.  
  23684.                 This keyword specifies the access level required to see or
  23685.                 access this file area.
  23686.  
  23687.              Barricade <menu_name> <barricade_file>
  23688.  
  23689.                 This keyword specifies a barricade file to be used for the
  23690.                 current file area. As long as the current menu is
  23691.                 <menu_name>, the barricade privilege level from
  23692.                 <barricade_file> will override the user's normal privilege
  23693.                 level. Please see section 4.6 for more information on bar-
  23694.                 ricade files.
  23695.  
  23696.              Desc <desc>
  23697.              Description <desc>
  23698.  
  23699.                 These keywords specify the description of the file area, as
  23700.                 you wish it to appear on the file area menu.
  23701.  
  23702.              Download <path>
  23703.  
  23704.                 This keyword tells Maximus that the files in this area can
  23705.                 be downloaded from <path>.
  23706.  
  23707.              End FileArea
  23708.  
  23709.                 This keyword tells SILT that the current file area defini-
  23710.                 tion is complete.
  23711.  
  23712.              FileArea <area>
  23713.  
  23714.                 This keyword tells SILT to begin a file area definition.
  23715.                 <area> is the "leaf" name of the file area; if the area is
  23716.                 contained within a file division, the name of the division
  23717.  
  23718.  
  23719.  
  23720.              18. Control File Reference                                431
  23721.  
  23722.                 will be added to the front of the string when writing the
  23723.                 area to the file area data file.
  23724.  
  23725.              FileDivisionBegin <name> <priv> <display_file> <description>
  23726.  
  23727.                 This keyword is used to begin a file area division. Divi-
  23728.                 sions can be used to create a multi-level, hierarchical
  23729.                 file area structure.
  23730.  
  23731.                 <name> is the name of the file area division. This should
  23732.                 be a very short tag identifying the area type. (It should
  23733.                 be short because it is added to the beginning of all area
  23734.                 names declared within the division.)
  23735.  
  23736.                 <acs> is the access control string required to view the
  23737.                 file division. Please note that the ACS specified for this
  23738.                 division has nothing to do with the ACS required to enter a
  23739.                 contained file area. (However, the ACS for the file areas
  23740.                 in the division will typically be at least as restrictive
  23741.                 as the ACS for the division.)
  23742.  
  23743.                 <display_file> is the name of the file area display file to
  23744.                 show when the user requests an area list of this division.
  23745.                 This file is only used if the corresponding Uses FileAreas
  23746.                 statement is enabled in the system control file. If you are
  23747.                 not using custom file area menus, specify a "." as the
  23748.                 filename.
  23749.  
  23750.                 <desc> is the description for this division, as it will ap-
  23751.                 pear on the file area menu.
  23752.  
  23753.              FileDivisionEnd
  23754.  
  23755.                 This statement tells SILT to end a file area division.
  23756.  
  23757.              FileList
  23758.  
  23759.                 This keyword specifies the location of a files.bbs-like
  23760.                 list for this file area. This is useful for CD-ROM handling
  23761.                 where there is no compatible files.bbs in the download di-
  23762.                 rectory for this area.
  23763.  
  23764.                 FB also uses this name as the "base" filename for creating
  23765.                 compiled file information. FB removes the extension from
  23766.                 the file you specify here, and it then adds .dat, .dmp and
  23767.                 .idx extensions to store the compile file information.
  23768.  
  23769.              MenuName <orig_menu> <replace_menu>
  23770.  
  23771.                 While Maximus is in this file area, when it is instructed
  23772.                 to display the menu <orig_menu>, it will instead display
  23773.                 <replace_menu>.
  23774.  
  23775.  
  23776.  
  23777.              18. Control File Reference                                432
  23778.  
  23779.              Override <menu_name> <option_type> <acs> [letter]
  23780.  
  23781.                 The Override keyword instructs Maximus to alter the privi-
  23782.                 lege level required to access a menu option while the user
  23783.                 is in this file area.
  23784.  
  23785.                 <menu_name> is the name of the menu containing the command
  23786.                 to be overridden. In most cases, this will be "FILE".
  23787.  
  23788.                 <option_type> is the menu option type to override. Any of
  23789.                 the keywords from the menus control file can be used here.
  23790.                 If you do not specify a [letter], the override will apply
  23791.                 to all options on the menu with a type of <option_type>.
  23792.  
  23793.                 <acs> is the new ACS required to access the menu option.
  23794.  
  23795.                 [letter] is the optional first letter of the command to be
  23796.                 overridden. If this letter is specified, the override will
  23797.                 only apply to menu commands which: are on the menu called
  23798.                 <menu_name>, which have an option type of <option_type> and
  23799.                 which have a first letter of [letter].
  23800.  
  23801.              Type <types>
  23802.  
  23803.                 This keyword specifies optional flags for a file area.
  23804.  
  23805.                 <types> can contain zero or more of the types from Table
  23806.                 18.11:
  23807.  
  23808.                 Table 18.11 File Area Types
  23809.  
  23810.                 Type        Description
  23811.  
  23812.                 CD          This area is stored on CD-ROM. This is equiva-
  23813.                             lent to Type Slow Staged NoNew.
  23814.                 DateAuto    Use automatic file dating for this area. FB
  23815.                             and Maximus will retrieve a file's size and
  23816.                             date information from the directory specified
  23817.                             in the Download path.
  23818.                 DateList    Use list-based file dating for this area. Both
  23819.                             Maximus and FB parse the file dates and sizes
  23820.                             correctly out of the files.bbs for this area
  23821.                             without looking for the directory entry.
  23822.                 DateManual  Use no file dating at all. The file descrip-
  23823.                             tions for this area may contain size and date
  23824.                             information, but they are not interpreted by
  23825.                             Maximus or FB in any way.
  23826.                 Free        This type is equivalent to specifying Type
  23827.                             FreeTime FreeSize.
  23828.                 FreeBytes   Both of these keywords allow all files in this
  23829.                 FreeSize    area to be downloaded without adding the files
  23830.                             to the user's file download limit. This is
  23831.                             equivalent to placing a "/b" in the descrip-
  23832.  
  23833.  
  23834.  
  23835.              18. Control File Reference                                433
  23836.  
  23837.                             tion for all files in the area.
  23838.                 FreeTime    This keyword allows users to download all of
  23839.                             the files in this area with no impact on their
  23840.                             time limit. This is equivalent to placing a
  23841.                             "/t" in the description for all files in the
  23842.                             area.
  23843.                 Hidden      This area is hidden from the normal File_Area
  23844.                             area listing. Users cannot see the area on the
  23845.                             menu or change to it using the File_Area
  23846.                             next/prior keys. However, the area can still
  23847.                             be accessed by name.
  23848.                 NoNew       This area is on a permanent storage medium and
  23849.                             should be excluded from new file checks.
  23850.                 Slow        File area is on a slow-access medium. Maximus
  23851.                             and SILT assume that the file area always ex-
  23852.                             ists (and therefore they do not check the di-
  23853.                             rectory when doing an area list). Maximus also
  23854.                             tries to access the directory entries in this
  23855.                             area as little as possible.
  23856.                 Staged      Files from this area are copied to the Stage
  23857.                             Path before a file download is initiated.
  23858.                             Use of a staging area allows file transfers to
  23859.                             proceed at full speed, and this feature will
  23860.                             also prevent wear and tear on a multi-disk CD-
  23861.                             ROM changer.
  23862.  
  23863.                             When using the internal transfer protocols,
  23864.                             Maximus copies each file to the staging area
  23865.                             before it is transferred, deleting it immedi-
  23866.                             ately after the file is sent.
  23867.  
  23868.                             For external protocols, Maximus copies all of
  23869.                             the files to the staging area at once, invokes
  23870.                             the external protocol, and then deletes all of
  23871.                             the files upon return.
  23872.  
  23873.  
  23874.              Upload
  23875.  
  23876.                 This keyword tells Maximus where to place files that are
  23877.                 uploaded in this area.
  23878.  
  23879.  
  23880.              18.8. Menu Control File
  23881.  
  23882.  
  23883.              18.8.1. Description
  23884.  
  23885.              The default menu control file is called menus.ctl. This file
  23886.              defines all of the menu options and commands that are acces-
  23887.              sible to users.
  23888.  
  23889.              A menu definition begins with the following line:
  23890.  
  23891.  
  23892.  
  23893.              18. Control File Reference                                434
  23894.  
  23895.                 Menu <name>
  23896.  
  23897.              and ends with the following:
  23898.  
  23899.                 End Menu
  23900.  
  23901.              All of the keywords between these two lines are considered
  23902.              part of the menu definition. A menu normally consists of a
  23903.              number of global menu options followed by one or more options
  23904.              to be displayed on the menu.
  23905.  
  23906.  
  23907.              18.8.2. Global Menu Options
  23908.  
  23909.              Global menu options may appear anywhere in a menu definition.
  23910.              These options can appear in any order.
  23911.  
  23912.              HeaderFile <filespec> [type]
  23913.  
  23914.                 This keyword specifies the name of a custom .bbs file to
  23915.                 display (or a MEX program to run) when entering a menu
  23916.                 area.
  23917.  
  23918.                 This file is displayed when entering the menu, and it is
  23919.                 also displayed after the user executes a command on the
  23920.                 menu. The HeaderFile is always displayed before the
  23921.                 MenuFile.
  23922.  
  23923.                 [type] can be zero or more of the following optional quali-
  23924.                 fiers:
  23925.  
  23926.                 * Novice
  23927.                 * Regular
  23928.                 * Expert
  23929.                 * RIP
  23930.  
  23931.                 If one or more [type] values are specified, Maximus will
  23932.                 display the HeaderFile only to users who have at least one
  23933.                 of the specified attributes. (By default, a HeaderFile is
  23934.                 displayed to all users.)
  23935.  
  23936.                 For example, given the following line:
  23937.  
  23938.                 HeaderFile  Misc\Msghdr  RIP Regular
  23939.  
  23940.                 Maximus would display the HeaderFile to users who either
  23941.                 have a help level of regular or who have RIPscrip graphics
  23942.                 enabled.
  23943.  
  23944.                 A MEX program can be used for the HeaderFile definition by
  23945.                 specifying a ":" as the first character in <filespec>. If
  23946.                 the user is just entering the message, the argument passed
  23947.  
  23948.  
  23949.  
  23950.              18. Control File Reference                                435
  23951.  
  23952.                 to the main function is "1". Otherwise, the argument passed
  23953.                 to the main function is "0".
  23954.  
  23955.              Menu <filestem>
  23956.  
  23957.                 This keyword begins a menu definition. <filestem> is the
  23958.                 root name of the menu file (without the .mnu extension).
  23959.                 <filestem> should not include a path.
  23960.  
  23961.              MenuColor <attr>
  23962.  
  23963.                 This command is normally only needed when using the
  23964.                 "MenuFile <filespec>" keyword in conjunction with hotkeys.
  23965.                 While these settings are in effect, if a user presses a key
  23966.                 during the display of the MenuFile, Maximus will abort the
  23967.                 display of the file and process the user's input immedi-
  23968.                 ately.
  23969.  
  23970.                 However, the MenuFile may use odd color combinations, so
  23971.                 this keyword tells Maximus to reset the color to <attr> be-
  23972.                 fore displaying the character entered by the user. <attr>
  23973.                 is a numeric AVATAR color code, as described in Appendix F.
  23974.  
  23975.              MenuFile <filename> [type]
  23976.  
  23977.                 This keyword instructs Maximus to display the specified
  23978.                 .bbs file instead of generating a "canned" display for this
  23979.                 menu. This option allows the SysOp to define a custom
  23980.                 graphics screen instead of the standard yellow and gray
  23981.                 menu display.
  23982.  
  23983.                 If you use this option on a message area menu, you are
  23984.                 strongly urged to also use the MenuLength keyword to ensure
  23985.                 that the menu output is displayed properly.
  23986.  
  23987.                 [type] can be zero or more of the following optional quali-
  23988.                 fiers:
  23989.  
  23990.                 * Novice
  23991.                 * Regular
  23992.                 * Expert
  23993.                 * RIP
  23994.  
  23995.                 If one or more [type] values are specified, Maximus will
  23996.                 display the MenuFile only to users who have at least one of
  23997.                 the specified attributes. By default, a MenuFile is dis-
  23998.                 played to all users.
  23999.  
  24000.              MenuLength <length>
  24001.  
  24002.                 This keyword is only used in conjunction with the MenuFile
  24003.                 keyword. This keyword informs Maximus that the custom
  24004.                 MenuFile display file is exactly <length> lines long. Maxi-
  24005.  
  24006.  
  24007.  
  24008.              18. Control File Reference                                436
  24009.  
  24010.                 mus uses this value to ensure that messages do not scroll
  24011.                 off the screen when the custom menu is displayed.
  24012.  
  24013.              OptionWidth <width>
  24014.  
  24015.                 This keyword tells Maximus to display each menu option in a
  24016.                 space of exactly <width> characters. The default value for
  24017.                 <width> is 20.
  24018.  
  24019.              Title <name>
  24020.  
  24021.                 This keyword defines the name of the menu as it appears to
  24022.                 the user. The value specified for <name> can also include
  24023.                 external program translation characters.
  24024.  
  24025.  
  24026.              18.8.3. Menu Option Modifiers
  24027.  
  24028.              These modifiers are simple flags that can be placed in front
  24029.              of menu options. Menu option modifiers modify the operation
  24030.              of a menu item in some manner.
  24031.  
  24032.              Ctl <option>
  24033.  
  24034.                 This modifier is obsolete.
  24035.  
  24036.              Conf <option>
  24037.  
  24038.                 This modifier instructs Maximus to display the following
  24039.                 menu option only in areas which have the Style Conf attrib-
  24040.                 ute.
  24041.  
  24042.              Echo <option>
  24043.  
  24044.                 This modifier instructs Maximus to display the following
  24045.                 menu option only in areas which have the Style Echo attrib-
  24046.                 ute.
  24047.  
  24048.              Local <option>
  24049.  
  24050.                 This modifier instructs Maximus to display the following
  24051.                 menu option only in areas which have the Style Local at-
  24052.                 tribute.
  24053.  
  24054.              Matrix <option>
  24055.  
  24056.                 This modifier instructs Maximus to display the following
  24057.                 menu option only in areas which have the Style Net attrib-
  24058.                 ute.
  24059.  
  24060.  
  24061.  
  24062.              18. Control File Reference                                437
  24063.  
  24064.              NoCLS <option>
  24065.  
  24066.                 This modifier is only used in conjunction with the
  24067.                 "Display_Menu" option. The NoCLS modifier instructs Maximus
  24068.                 not to clear the screen before displaying the specified
  24069.                 menu.
  24070.  
  24071.              NoDsp <option>
  24072.  
  24073.                 This modifier instructs Maximus not to display the follow-
  24074.                 ing menu option on the generated menu display. This modi-
  24075.                 fier is useful for creating hidden commands and linked menu
  24076.                 options.
  24077.  
  24078.              NoRIP <option>
  24079.  
  24080.                 This modifier instructs Maximus to display the following
  24081.                 menu option only when the user does not have RIPscrip
  24082.                 graphics enabled.
  24083.  
  24084.              ReRead <option>
  24085.  
  24086.                 This modifier is only used in conjunction with the
  24087.                 Xtern_Dos and Xtern_Run menu options.
  24088.  
  24089.                 This modifier instructs Maximus to re-read the user's las-
  24090.                 tus##.bbs after running the external command. This option
  24091.                 is useful when the external program modifies the user file
  24092.                 and wishes to communicate the changes back to Maximus.
  24093.  
  24094.              RIP <option>
  24095.  
  24096.                 This modifier instructs Maximus to display the following
  24097.                 menu option only to those users who have RIPscrip graphics
  24098.                 enabled.
  24099.  
  24100.              UsrLocal <option>
  24101.  
  24102.                 This modifier instructs Maximus to display the following
  24103.                 menu option only when the user is logged in at the local
  24104.                 console. This modifier is useful for creating menu commands
  24105.                 that can only be used locally by the SysOp.
  24106.  
  24107.              UsrRemote <option>
  24108.  
  24109.                 This modifier instructs Maximus to display the following
  24110.                 menu option only when the user is logged in from remote.
  24111.                 This modifier is useful for hiding commands that are only
  24112.                 useful for remote callers, such as call-back verification
  24113.                 programs.
  24114.  
  24115.  
  24116.  
  24117.              18. Control File Reference                                438
  24118.  
  24119.              18.8.4. Menu Option Format
  24120.  
  24121.              Maximus supports up to 127 menu options on a single menu. The
  24122.              format for each menu option looks like this:
  24123.  
  24124.                 [modifier] <option_name> [arg] <acs> "<desc>" ["kp"]
  24125.  
  24126.              [modifier] can be zero or more of the optional menu option
  24127.              modifiers, as described in the previous section.
  24128.  
  24129.              <option_name> is the name of the menu command to execute when
  24130.              the user selects this option. An alphabetical list of menu
  24131.              commands can be found in section 18.8.5.
  24132.  
  24133.              [arg] is the optional argument for the menu command. This
  24134.              field must not be specified unless the menu command specifi-
  24135.              cally requires an argument. The description for each menu
  24136.              command indicates whether or not the command requires an ar-
  24137.              gument.
  24138.  
  24139.              <acs> is the access control string required to view or exe-
  24140.              cute the menu option.
  24141.  
  24142.              <desc> is the description of the menu command, as it appears
  24143.              on the menu. The description must be enclosed in quotes.
  24144.              Maximus uses the first letter of the description as the se-
  24145.              lection character for the command; this means that the menu
  24146.              option will be executed when the user presses this character.
  24147.              Normally, the first letter of <desc> must be unique among op-
  24148.              tions on a single menu.
  24149.  
  24150.              However, Maximus also allows menu options to be connected to
  24151.              the function keys and arrow keys on an IBM-style keyboard.
  24152.              These special keys work on the local console, and they also
  24153.              work for any user with a terminal program that supports
  24154.              "DoorWay mode."
  24155.  
  24156.              If a back-quote ("`") is specified as the first character of
  24157.              <desc>, Maximus will interpret the following number as the
  24158.              scan code of the key to assign to the menu option. (A list of
  24159.              scan codes can be found in most technical PC reference manu-
  24160.              als. In general, scan codes are related to the placement of
  24161.              keys on the keyboard.)
  24162.  
  24163.              The following key assignments are used on the default message
  24164.              area menu:
  24165.  
  24166.                 NoDsp   Msg_Change         Transient "`46"     ; alt-c
  24167.                 NoDsp   Read_Previous      Transient "`75"     ; left
  24168.                 NoDsp   Read_Original      Transient "`115"    ; ctrl-left
  24169.                 NoDsp   Read_Next          Transient "`77"     ; right
  24170.                 NoDsp   Read_Reply         Transient "`116"    ; ctrl-right
  24171.                 NoDsp   Msg_Reply          Transient "`16"     ; alt-q
  24172.  
  24173.  
  24174.  
  24175.              18. Control File Reference                                439
  24176.  
  24177.                 NoDsp   Msg_Reply          Transient "`19"     ; alt-r
  24178.                 NoDsp   Msg_Kill           Transient "`37" "=" ; alt-k
  24179.  
  24180.              [kp] is the optional Key_Poke text. This argument must be en-
  24181.              closed in quotes. When the user selects this menu option,
  24182.              Maximus will automatically insert the text in [kp] into the
  24183.              keyboard buffer. This functionality is identical to that pro-
  24184.              vided by the Key_Poke menu option.
  24185.  
  24186.  
  24187.              18.8.5. Alphabetical Menu Option Listing
  24188.  
  24189.              Chat_CB
  24190.  
  24191.                 Invoke the internal multinode chat facility (in CB simula-
  24192.                 tor mode). Please see section 7.2 for more information.
  24193.  
  24194.              Chat_Page
  24195.  
  24196.                 Prompt the user for a node number to page and then send a
  24197.                 chat request to the specified user. After the message is
  24198.                 sent, Maximus places the user inside the multinode chat un-
  24199.                 til the other user responds to the page. Please see section
  24200.                 7.2 for more information.
  24201.  
  24202.              Chat_Pvt
  24203.  
  24204.                 Invoke the internal multinode chat (in private chat mode).
  24205.                 Please see section 7.2 for more information.
  24206.  
  24207.              Chat_Toggle
  24208.  
  24209.                 Toggle the user's multinode chat availability flag.
  24210.  
  24211.              Chg_Alias
  24212.  
  24213.                 Change the user's alias to a new value. The new alias must
  24214.                 not conflict with the name or alias of any other user on
  24215.                 the system.
  24216.  
  24217.              Chg_Archiver
  24218.  
  24219.                 Select the default compression method for downloading QWK
  24220.                 packets. Normally, the user is prompted to select an ar-
  24221.                 chiver for every download. This menu option can be used to
  24222.                 select a default archiver and suppress the prompt.
  24223.  
  24224.              Chg_City
  24225.  
  24226.                 Change the user's city to a new value.
  24227.  
  24228.  
  24229.  
  24230.              18. Control File Reference                                440
  24231.  
  24232.              Chg_Clear
  24233.  
  24234.                 Toggle the user's clearscreen setting.
  24235.  
  24236.              Chg_Editor
  24237.  
  24238.                 Toggle the user's full-screen editor flag. This option tog-
  24239.                 gles between the line editor and the full-screen MaxEd edi-
  24240.                 tor.
  24241.  
  24242.              Chg_FSR
  24243.  
  24244.                 Toggle the user's full-screen reader flag. When enabled, an
  24245.                 attractive message header is displayed to users with ANSI
  24246.                 or AVATAR graphics. All of the fields in the message header
  24247.                 are presented at once, and the user can move back and forth
  24248.                 between the fields using the cursor keys or tab key.
  24249.  
  24250.              Chg_Help
  24251.  
  24252.                 Change the user's help level. Maximus supports the novice,
  24253.                 regular and expert help levels.
  24254.  
  24255.              Chg_Hotkeys
  24256.  
  24257.                 Toggle the user's hotkeys setting. With hotkeys enabled,
  24258.                 menu commands are executed as soon as the key is pressed,
  24259.                 without waiting for the user to press <enter>.
  24260.  
  24261.              Chg_IBM
  24262.  
  24263.                 Toggle the user's "IBM extended ASCII" flag. This controls
  24264.                 whether Maximus sends high-bit characters directly or
  24265.                 whether it translates those characters to ASCII equiva-
  24266.                 lents.
  24267.  
  24268.              Chg_Language
  24269.  
  24270.                 Select a new language file. Any of the language files
  24271.                 specified in the language control file can be selected
  24272.                 here.
  24273.  
  24274.              Chg_Length
  24275.  
  24276.                 Change the user's screen length to a new value.
  24277.  
  24278.              Chg_More
  24279.  
  24280.                 Toggle the display of "More [Y,n,=]?" prompts.
  24281.  
  24282.  
  24283.  
  24284.              18. Control File Reference                                441
  24285.  
  24286.              Chg_Nulls
  24287.  
  24288.                 Change the number of NUL characters sent after every trans-
  24289.                 mitted line.
  24290.  
  24291.              Chg_Password
  24292.  
  24293.                 Change the user's password to a new value.
  24294.  
  24295.              Chg_Phone
  24296.  
  24297.                 Change the user's telephone number.
  24298.  
  24299.              Chg_Protocol
  24300.  
  24301.                 Select a new default protocol. Normally, Maximus prompts
  24302.                 the user to select a file transfer protocol for every up-
  24303.                 load and download. A default protocol can be selected to
  24304.                 suppress this prompt.
  24305.  
  24306.              Chg_Realname
  24307.  
  24308.                 This option is obsolete.
  24309.  
  24310.              Chg_RIP
  24311.  
  24312.                 Toggle the user's RIPscrip graphics setting. Enabling
  24313.                 RIPscrip also forces ANSI graphics and screen clearing to
  24314.                 be enabled.
  24315.  
  24316.              Chg_Tabs
  24317.  
  24318.                 Toggle the user's "tab" setting. This flag tells Maximus if
  24319.                 it can transmit tab characters to the user; if not, it will
  24320.                 translate tabs into sequences of up to eight spaces.
  24321.  
  24322.              Chg_Userlist
  24323.  
  24324.                 Toggle the user's "display in userlist" flag. If this op-
  24325.                 tion is set to no, the user is never displayed in the us-
  24326.                 erlist. If this option is set to yes, the user may be dis-
  24327.                 played in the user list, depending on whether or not the
  24328.                 Flags Hide attribute is specified for the user's class in
  24329.                 the access control file.
  24330.  
  24331.              Chg_Video
  24332.  
  24333.                 Select a new video mode. Maximus supports the TTY, ANSI and
  24334.                 AVATAR video modes.
  24335.  
  24336.              Chg_Width
  24337.  
  24338.                 Change the user's screen width to a new value.
  24339.  
  24340.  
  24341.  
  24342.              18. Control File Reference                                442
  24343.  
  24344.              Clear_Stacked
  24345.  
  24346.                 Clear the user's command-stack buffer. This will eliminate
  24347.                 any leftover input in the keyboard input buffer. This op-
  24348.                 tion is normally linked with another menu option.
  24349.  
  24350.              Display_File <filespec>
  24351.  
  24352.                 This command displays the .bbs file specified by the
  24353.                 <filespec> argument. This argument can also include exter-
  24354.                 nal program translation characters. (However, remember that
  24355.                 translation characters used in filenames must begin with a
  24356.                 "+" character, not a "%" character.)
  24357.  
  24358.                 For example, to display a file called bps<b>.bbs, where <b>
  24359.                 is the current baud rate, the following line can be used:
  24360.  
  24361.                 Display_File    D:\Bps+B        Demoted "BaudFile"
  24362.  
  24363.              Display_Menu <name>
  24364.  
  24365.                 This menu option instructs Maximus to display the menu
  24366.                 specified by <name>. The <name> argument must not include a
  24367.                 path or extension.
  24368.  
  24369.                 Display_Menu calls are "flat," in that the called menu does
  24370.                 not implicitly know how to return to the calling menu
  24371.                 (without using an explicit Display_Menu with the calling
  24372.                 menu's name). If this behavior is not desired, see the
  24373.                 Link_Menu menu option for a more robust approach.
  24374.  
  24375.              Edit_Abort
  24376.  
  24377.                 Abort entry of the current message. This option is only
  24378.                 valid within the line editor.
  24379.  
  24380.              Edit_Continue
  24381.  
  24382.                 Append to a message in the line editor, or return to the
  24383.                 full-screen MaxEd display. This option is only valid within
  24384.                 one of the editor menus.
  24385.  
  24386.              Edit_Delete
  24387.  
  24388.                 Delete a line from a message in the line editor. This op-
  24389.                 tion is only valid within the line editor.
  24390.  
  24391.              Edit_Edit
  24392.  
  24393.                 Modify one line within the message. This option is only
  24394.                 valid within the line editor.
  24395.  
  24396.  
  24397.  
  24398.              18. Control File Reference                                443
  24399.  
  24400.              Edit_From
  24401.  
  24402.                 Edit the From: field of a message. This option is only
  24403.                 valid within one of the editor menus.
  24404.  
  24405.              Edit_Handling
  24406.  
  24407.                 Modify the message attributes associated with a message.
  24408.                 This option should only be accessible to the SysOp. This
  24409.                 option is only valid within one of the editor menus.
  24410.  
  24411.              Edit_Insert
  24412.  
  24413.                 Insert a line into the message. This option is only valid
  24414.                 within the line editor.
  24415.  
  24416.              Edit_List
  24417.  
  24418.                 List the lines in the current message. This option is only
  24419.                 valid within the line editor.
  24420.  
  24421.              Edit_Quote
  24422.  
  24423.                 Copy text from the message that the user is replying to and
  24424.                 place it in the current message. This option is only valid
  24425.                 within the line editor.
  24426.  
  24427.              Edit_Save
  24428.  
  24429.                 Save the message and place it in the message base. This op-
  24430.                 tion is only valid within the line editor.
  24431.  
  24432.              Edit_Subj
  24433.  
  24434.                 Edit the Subject: field of the message. This option is only
  24435.                 valid within one of the editor menus.
  24436.  
  24437.              Edit_To
  24438.  
  24439.                 Edit the To: field of the message. This option is only
  24440.                 valid within one of the editor menus.
  24441.  
  24442.              File_Area
  24443.  
  24444.                 Prompt the user to select a new file area.
  24445.  
  24446.              File_Contents
  24447.  
  24448.                 Display the contents of a compressed file. Maximus supports
  24449.                 files compressed using the ARC, ARJ, PAK, ZIP, and LZH com-
  24450.                 pression methods.
  24451.  
  24452.  
  24453.  
  24454.              18. Control File Reference                                444
  24455.  
  24456.              File_Download
  24457.  
  24458.                 Download (send) a file from the file areas.
  24459.  
  24460.              File_Hurl
  24461.  
  24462.                 Move a file from one file area to another.
  24463.  
  24464.              File_Kill
  24465.  
  24466.                 Delete a file from the current file area.
  24467.  
  24468.              File_Locate
  24469.  
  24470.                 Search all file areas for a file with a certain filename or
  24471.                 description. This command can also be used to display a
  24472.                 list of new files.
  24473.  
  24474.              File_NewFiles
  24475.  
  24476.                 Search for new files in all file areas. This command is
  24477.                 identical to the [newfiles] MECCA token.
  24478.  
  24479.              File_Override
  24480.  
  24481.                 Temporarily change the download path for the current area.
  24482.                 This function allows the SysOp to access any directory on
  24483.                 the BBS as if it were a normal file area. See also the
  24484.                 File_Raw menu option.
  24485.  
  24486.              File_Raw
  24487.  
  24488.                 Display a raw directory of the current file area. This op-
  24489.                 tion shows all files in the directory, not just those con-
  24490.                 tained in files.bbs.
  24491.  
  24492.              File_Tag
  24493.  
  24494.                 Add ("tag") a file and place it in the downloaded queue.
  24495.                 The files tagged by this command can be downloaded later
  24496.                 using the File_Download command.
  24497.  
  24498.              File_Titles
  24499.  
  24500.                 Display a list of all files in the current file area, in-
  24501.                 cluding the name, timestamp and description of each file.
  24502.                 To produce this listing, Maximus reads the files.bbs file
  24503.                 for the current area.
  24504.  
  24505.              File_Type
  24506.  
  24507.                 Display the contents of an ASCII text file in the current
  24508.                 file area.
  24509.  
  24510.  
  24511.  
  24512.              18. Control File Reference                                445
  24513.  
  24514.              File_Upload
  24515.  
  24516.                 Upload (receive) a file.
  24517.  
  24518.                 Maximus can automatically exclude specific types of files
  24519.                 from being uploaded. When the user uploads a file, Maximus
  24520.                 compares the filenames of the files to be uploaded with the
  24521.                 names specified in the \max\badfiles.bbs file. If an up-
  24522.                 loaded file is named in that file, Maximus will display the
  24523.                 \max\misc\bad_upld.bbs file and abort the upload.
  24524.  
  24525.                 Filenames specified in badfiles.bbs can be full filenames
  24526.                 or wildcard file specifications. Spaces or newlines can be
  24527.                 used to separate file specifications. For example:
  24528.  
  24529.                 MAKE$$$.TXT MAKECASH.*
  24530.                 *.RBS *.GBS *.BBS
  24531.                 *.GIF *.JPG *.TIF
  24532.  
  24533.                 Uploaded files which are excluded by this list are auto-
  24534.                 matically deleted and the user is not given credit for the
  24535.                 upload.
  24536.  
  24537.              Goodbye
  24538.  
  24539.                 Log off the system.
  24540.  
  24541.              Key_Poke <keys>
  24542.  
  24543.                 Insert the keystrokes specified by <keys> into the user's
  24544.                 keystroke buffer. Maximus behaves just as if the user had
  24545.                 entered the keystrokes manually. Ensure that all spaces are
  24546.                 replaced with underscores.
  24547.  
  24548.                 For example:
  24549.  
  24550.                 Key_Poke        bayl      Demoted "*List new msgs"
  24551.  
  24552.                 If this command is executed from the message menu, it will
  24553.                 select the Browse / All / Your / List command and display a
  24554.                 list of all new messages addressed to the current user.
  24555.  
  24556.                 External program translation characters can also be in-
  24557.                 cluded in the <keys> sequence. To place an <enter> key-
  24558.                 stroke in the input sequence, a ";" or "|" character will
  24559.                 work with most (but not all) commands.
  24560.  
  24561.        Note!    Keys can also be implicitly placed in the keyboard buffer
  24562.                 by placing an extra set of quotation marks after the name
  24563.                 of a menu option. For example, the following menu option:
  24564.  
  24565.                 Msg_Browse              Demoted "*List new msgs" "ayl"
  24566.  
  24567.  
  24568.  
  24569.              18. Control File Reference                                446
  24570.  
  24571.                 automatically places the "a," "y" and "l" characters in the
  24572.                 keyboard buffer before executing the Browse command.
  24573.  
  24574.              Leave_Comment
  24575.  
  24576.                 Place the user in the message editor and address a message
  24577.                 to the SysOp. The message is placed in the area defined by
  24578.                 Comment Area in the system control file.
  24579.  
  24580.              Link_Menu <name>
  24581.  
  24582.                 This menu option can be used to nest menus. When menu
  24583.                 <name> is displayed by this option, the Return menu option
  24584.                 can be used to return back to the calling menu. Maximus
  24585.                 supports up to eight nested Link_Menu options.
  24586.  
  24587.                 For example, if the following option is placed on your main
  24588.                 menu:
  24589.  
  24590.                 Link_Menu CHAT               Demoted    "/Chat menu
  24591.  
  24592.                 then placing the following option on your chat menu allows
  24593.                 Maximus to return to the main menu when the "M" key is se-
  24594.                 lected:
  24595.  
  24596.                 Return                       Demoted    "Main menu"
  24597.  
  24598.              Msg_Area
  24599.  
  24600.                 Prompt the user to select a new message area.
  24601.  
  24602.              Msg_Browse
  24603.  
  24604.                 Invoke the Browse function. This option allows the user to
  24605.                 selectively read, list, or pack messages for the QWK mail
  24606.                 packer. Messages can be selected by area, by message type,
  24607.                 and by a user-defined search of the message header and
  24608.                 body.
  24609.  
  24610.              Msg_Change
  24611.  
  24612.                 Modify an existing message. Maximus only allows users to
  24613.                 modify messages that have not been:
  24614.  
  24615.                 * read by the addressee,
  24616.                 * scanned out as EchoMail, or
  24617.                 * sent as NetMail
  24618.  
  24619.                 However, if the user's class has the MailFlags MsgAttrAny
  24620.                 attribute specified, Maximus will allow the user to modify
  24621.                 the message anyway.
  24622.  
  24623.  
  24624.  
  24625.              18. Control File Reference                                447
  24626.  
  24627.              Msg_Checkmail
  24628.  
  24629.                 Invoke the built-in mailchecker. This option is equivalent
  24630.                 to the [msg_checkmail] MECCA token.
  24631.  
  24632.              Msg_Current
  24633.  
  24634.                 Redisplay the current message.
  24635.  
  24636.              Msg_Download_Attach
  24637.  
  24638.                 Lists unreceived file attaches addressed to the current
  24639.                 user. This command then prompts the user to download each
  24640.                 file attach.
  24641.  
  24642.              Msg_Edit_User
  24643.  
  24644.                 Invoke the user editor and automatically perform a search
  24645.                 on the user listed in the From: field of the current mes-
  24646.                 sage. This option is normally only accessible to the SysOp.
  24647.  
  24648.              Msg_Enter
  24649.  
  24650.                 Create a new message in the current area.
  24651.  
  24652.              Msg_Forward
  24653.  
  24654.                 Forward a copy of the current message to another user.
  24655.  
  24656.              Msg_Hurl
  24657.  
  24658.                 Move a message from one area to another.
  24659.  
  24660.              Msg_Kill
  24661.  
  24662.                 Delete a message from the current area. The message must be
  24663.                 either To: or From: the current user. (Maximus will also
  24664.                 allow users in a class with the MailFlags ShowPvt attribute
  24665.                 to delete messages which are addressed to other users.)
  24666.  
  24667.              Msg_Kludges
  24668.  
  24669.                 Toggle display of the <ctrl-a> "kludge" lines at the begin-
  24670.                 ning of messages. These lines normally hold message routing
  24671.                 and control information. This option is normally only
  24672.                 available to the SysOp.
  24673.  
  24674.              Msg_Reply
  24675.  
  24676.                 Reply to the current message. The reply is placed in the
  24677.                 current area.
  24678.  
  24679.  
  24680.  
  24681.              18. Control File Reference                                448
  24682.  
  24683.              Msg_Reply_Area <area>
  24684.  
  24685.                 Reply to the current message in another area.
  24686.  
  24687.                 If the <area> argument specifies an explicit message area
  24688.                 name, the reply is automatically placed in the indicated
  24689.                 area. If a "." is specified, the user is prompted to select
  24690.                 a message area for the reply.
  24691.  
  24692.              Msg_Restrict
  24693.  
  24694.                 Limit QWK message downloads on the basis of message date.
  24695.                 Users can set this field so that messages that arrived on
  24696.                 the system prior to a certain date are not downloaded. This
  24697.                 date remains in effect for the current session only.
  24698.  
  24699.              Msg_Tag
  24700.  
  24701.                 Tag (select) specific message areas of interest. The list
  24702.                 of tagged areas can be later recalled when using the
  24703.                 Msg_Browse command.
  24704.  
  24705.              Msg_Unreceive
  24706.  
  24707.                 "Unreceive" the current message. This option resets the
  24708.                 "received" flag for the current message, regardless of the
  24709.                 message's author. This option should normally only be
  24710.                 available to the SysOp.
  24711.  
  24712.              Msg_Upload
  24713.  
  24714.                 Create a message by uploading a file, rather than invoking
  24715.                 one of the internal editors. Maximus still prompts the user
  24716.                 for the message header information, but after the header is
  24717.                 created, it prompts the user to upload an ASCII text file.
  24718.  
  24719.              Msg_Upload_QWK
  24720.  
  24721.                 Upload a .rep reply packet generated by a QWK off-line
  24722.                 reader.
  24723.  
  24724.              Msg_Xport
  24725.  
  24726.                 Export a message to an ASCII text file. This option allows
  24727.                 the user to specify an explicit path and filename, so only
  24728.                 the SysOp should be able to access this command.
  24729.  
  24730.                 To print a message, select the Msg_Xport option and specify
  24731.                 a filename of "prn".
  24732.  
  24733.  
  24734.  
  24735.              18. Control File Reference                                449
  24736.  
  24737.              Press_Enter
  24738.  
  24739.                 Set the text color to white and prompt the user to press
  24740.                 <enter>. This option is normally linked with another menu
  24741.                 option.
  24742.  
  24743.              Read_DiskFile
  24744.  
  24745.                 Import an ASCII text file from the local disk and place it
  24746.                 in the current message. This option can only be used from
  24747.                 one of the editor menus. This option allows the user to
  24748.                 specify an explicit path and filename, so it should only be
  24749.                 available to the SysOp.
  24750.  
  24751.              Read_Individual
  24752.  
  24753.                 Read a specific message number in the current area.
  24754.  
  24755.              Read_Next
  24756.  
  24757.                 Read the next message in the current area.
  24758.  
  24759.              Read_Nonstop
  24760.  
  24761.                 Display all of the messages in the area without pausing af-
  24762.                 ter each message. If the last reading command was
  24763.                 Read_Next, messages are displayed in forward order. Other-
  24764.                 wise, if the last reading command was Read_Previous, mes-
  24765.                 sages are displayed in reverse order.
  24766.  
  24767.              Read_Original
  24768.  
  24769.                 Read the original message in the current thread. See also
  24770.                 Read_Reply.
  24771.  
  24772.              Read_Previous
  24773.  
  24774.                 Read the previous message in the current area.
  24775.  
  24776.              Read_Reply
  24777.  
  24778.                 Display the next message in the current thread. See also
  24779.                 Read_Original.
  24780.  
  24781.              Return
  24782.  
  24783.                 Return from a menu that was called with the Link_Menu op-
  24784.                 tion.
  24785.  
  24786.              Same_Direction
  24787.  
  24788.                 Continue reading messages in the same direction, as speci-
  24789.                 fied by the last Read_Previous or Read_Next menu option.
  24790.  
  24791.  
  24792.  
  24793.              18. Control File Reference                                450
  24794.  
  24795.              User_Editor
  24796.  
  24797.                 Invoke the system user editor. This option should only be
  24798.                 accessible to the SysOp.
  24799.  
  24800.              Userlist
  24801.  
  24802.                 Display a list of all users on the system. Users who dis-
  24803.                 able the "In UserList" setting in their user profile are
  24804.                 not displayed. In addition, users in classes with the Flags
  24805.                 Hide attribute are never displayed.
  24806.  
  24807.              Version
  24808.  
  24809.                 Display the Maximus version number and credit information.
  24810.                 Maximus prompts the user to press <enter> after displaying
  24811.                 this screen.
  24812.  
  24813.              Who_Is_On
  24814.  
  24815.                 On a multinode system, this displays the names, task num-
  24816.                 bers, and status of users who are logged on.
  24817.  
  24818.              Xtern_Dos <cmd>
  24819.              Xtern_Erlvl <errorlevel>[_<cmd>]
  24820.              Xtern_Run <cmd>
  24821.  
  24822.                 Run the external program specified by <cmd>. If <cmd> has
  24823.                 arguments, ensure that all spaces are replaced with under-
  24824.                 scores.
  24825.  
  24826.                 Please see section 6 for more information on running exter-
  24827.                 nal programs.
  24828.  
  24829.              Yell
  24830.  
  24831.                 Page the system operator. Maximus will play one of the yell
  24832.                 tunes if yelling is currently enabled.
  24833.  
  24834.  
  24835.              18.9. Access Control File
  24836.  
  24837.  
  24838.              18.9.1. Description
  24839.  
  24840.              The default access control file is access.ctl. This file de-
  24841.              fines the user classes and privilege levels for all users on
  24842.              the system.
  24843.  
  24844.  
  24845.  
  24846.              18. Control File Reference                                451
  24847.  
  24848.              18.9.2. Alphabetical Keyword Listing
  24849.  
  24850.              Access <name>
  24851.  
  24852.                 This keyword begins a class definition. <name> is the
  24853.                 unique symbolic name for this class. This name may be used
  24854.                 interchangeably with the argument specified for Level.
  24855.  
  24856.              Calls <no>
  24857.  
  24858.                 This keyword specifies the maximum number of times per day
  24859.                 that users of this class are allowed to log on. If <no> is
  24860.                 -1, users can log on an unlimited number of times.
  24861.  
  24862.              Cume <mins>
  24863.  
  24864.                 This keyword specifies the maximum amount of time per day
  24865.                 that users of this class are allowed to log on the system.
  24866.                 See also the Time keyword.
  24867.  
  24868.              Desc <desc>
  24869.  
  24870.                 This keyword specifies an optional description for the
  24871.                 privilege level. If no description is specified, the name
  24872.                 of the class itself is used.
  24873.  
  24874.              End Access
  24875.  
  24876.                 This keyword marks the end of an access level definition.
  24877.  
  24878.              FileLimit <kbs>
  24879.  
  24880.                 This keyword specifies the maximum number of kilobytes that
  24881.                 users in this class are allowed to download per day.
  24882.  
  24883.              FileRatio <amt>
  24884.  
  24885.                 This keyword specifies the download:upload ratio for users
  24886.                 in this class. After exceeding the RatioFree level of down-
  24887.                 loads, the user must upload files such that the down-
  24888.                 load:upload ratio is at least <amt>. Otherwise, Maximus
  24889.                 will not allow the user to download files.
  24890.  
  24891.              Flags <words>
  24892.  
  24893.                 Set a number of attributes for users of this class.
  24894.  
  24895.                 Zero or more of the options from Table 18.12 can be speci-
  24896.                 fied for <words>:
  24897.  
  24898.  
  24899.  
  24900.              18. Control File Reference                                452
  24901.  
  24902.                 Table 18.12 Access Flags
  24903.  
  24904.                 Word          Description
  24905.  
  24906.                 DloadHidden   Users can download files which are hidden or
  24907.                               not listed in the files list for the current
  24908.                               file area.
  24909.                 Hangup        Users of this class are not allowed to log
  24910.                               on. Maximus will hang up immediately when a
  24911.                               user of this class calls the system.
  24912.                 Hide          Users of this class are not displayed in the
  24913.                               system user list.
  24914.                 NoFileLimit   The download byte/ratio limits do not apply
  24915.                               to users in this class.
  24916.                 NoTimeLimit   Disables time limit and input timeout check-
  24917.                               ing for users in this class.
  24918.                 NoLimits      This is equivalent to specifying both
  24919.                               NoFileLimit and NoTimeLimit.
  24920.                 ShowAllFiles  When displaying a file list, display all
  24921.                               files, even those which were hidden by plac-
  24922.                               ing an "@" as the first character in the
  24923.                               file area list.
  24924.                 ShowHidden    Users in this class can see all users in the
  24925.                               user list, regardless of "do not display in
  24926.                               list" settings.
  24927.                 UploadAny     Users in this class can upload any type of
  24928.                               file, bypassing checks for .bbs, .gbs, and
  24929.                               .rbs files, and also bypassing the checks
  24930.                               for files listed in badfiles.bbs.
  24931.  
  24932.  
  24933.              Key <letter>
  24934.  
  24935.                 This keyword defines the one-character key used to specify
  24936.                 this user class level. This key is used by some of the ob-
  24937.                 solete MECCA tokens (including [?below], [?above], [?line],
  24938.                 and [?file]).
  24939.  
  24940.              Level <lvl>
  24941.  
  24942.                 This keyword specifies the numeric privilege level for this
  24943.                 user class. <lvl> must be between 0 and 65535 (inclusive).
  24944.                 <lvl> must be unique among all user classes.
  24945.  
  24946.              LoginFile <filename>
  24947.  
  24948.                 This keyword specifies the file to be displayed to users in
  24949.                 this class as soon as they log on.
  24950.  
  24951.              LogonBaud <baud>
  24952.  
  24953.                 Users of this class must have a speed of at least <baud>
  24954.                 before they are allowed to log on.
  24955.  
  24956.  
  24957.  
  24958.              18. Control File Reference                                453
  24959.  
  24960.              MailFlags <words>
  24961.  
  24962.                 These flags control a number of options related to entering
  24963.                 messages and viewing mail.
  24964.  
  24965.                 Any of the values from Table 18.13 can be specified for
  24966.                 <words>:
  24967.  
  24968.                 Table 18.13 Access Mail Flags
  24969.  
  24970.                 Type             Description
  24971.  
  24972.                 Editor           If an external message editor is defined,
  24973.                                  both local and remote users in this class
  24974.                                  are permitted to use it.
  24975.                 LocalEditor      If an external message editor is defined,
  24976.                                  local users in this class are permitted
  24977.                                  to use it.
  24978.                 MsgAttrAny       Users in this class are allowed to modify
  24979.                                  any message or set any attribute in a
  24980.                                  NetMail message.
  24981.                 NetFree          Users in this class are not charged for
  24982.                                  entering NetMail messages. The user's
  24983.                                  NetMail credit and debit fields are not
  24984.                                  modified.
  24985.                 NoRealName       Users in this class will never have the
  24986.                                  REALNAME kludge added to messages that
  24987.                                  they create.
  24988.                 ShowPvt          Users in this class can see all messages,
  24989.                                  regardless of the message addressee or
  24990.                                  private flag.
  24991.                 WriteRdOnly      Users in this class can post messages in
  24992.                                  areas marked as Style ReadOnly.
  24993.  
  24994.  
  24995.              OldPriv <value>
  24996.  
  24997.                 This keyword specifies the "Maximus 2.0 compatibility
  24998.                 privilege level". Maximus 3.0 itself does not use this
  24999.                 value; however, SILT will use this number when writing data
  25000.                 files that are compatible with Maximus 2.0.
  25001.  
  25002.                 This field is not optional. (If you create additional user
  25003.                 classes, copy the Oldpriv value from one of the existing
  25004.                 classes with a similar privilege level.)
  25005.  
  25006.              RatioFree <kbs>
  25007.  
  25008.                 Users in this class are allowed to download <kbs> kilobytes
  25009.                 of files before the FileRatio limit is applied.
  25010.  
  25011.  
  25012.  
  25013.              18. Control File Reference                                454
  25014.  
  25015.              Time <mins>
  25016.  
  25017.                 Users in this class are allowed to log on for up to <mins>
  25018.                 minutes per session.
  25019.  
  25020.              UploadReward <value>
  25021.  
  25022.                 This keyword tells Maximus how much time to give back to
  25023.                 users who upload files.
  25024.  
  25025.                 A <value> of 100% adds back only the amount of time that
  25026.                 the user spent uploading the file, so the user will have
  25027.                 the same amount of time left when the upload is complete.
  25028.  
  25029.                 To give users extra time for uploading files, use a <value>
  25030.                 in excess of 100%.
  25031.  
  25032.                 To provide no compensation for uploads, set the reward to
  25033.                 0%.
  25034.  
  25035.              UserFlags <value>
  25036.  
  25037.                 This keyword specifies an optional set of flags. These
  25038.                 class flags can be used in MEX programs to test for various
  25039.                 class attributes. Maximus itself does not use this field.
  25040.  
  25041.                 This value may be given in decimal or hexadecimal.
  25042.                 (Hexadecimal constants are specified using the "0x" or "$"
  25043.                 prefix.)
  25044.  
  25045.              XferBaud <baud>
  25046.  
  25047.                 Users in this class must have a speed of at least <baud> to
  25048.                 download files.
  25049.  
  25050.  
  25051.              18.10. Protocol Control File
  25052.  
  25053.              The default protocol control file is protocol.ctl. Maximus
  25054.              can directly use external protocols such as DSZ, MPt, Kermit,
  25055.              and others. Maximus has a configurable, control-file-driven
  25056.              protocol system which can interface to almost any type of ex-
  25057.              ternal protocol.
  25058.  
  25059.              In addition to "standard" protocols such as DSZ, Maximus also
  25060.              supports "Opus-compatible" protocols, such as OKermit, OASCII
  25061.              and others. These protocols must also be defined in the pro-
  25062.              tocol control file, but they use a slightly different decla-
  25063.              ration format.
  25064.  
  25065.  
  25066.  
  25067.              18. Control File Reference                                455
  25068.  
  25069.              18.10.1. Alphabetical Keyword Listing
  25070.  
  25071.              ControlFile <filespec>
  25072.  
  25073.                 This keyword defines the name of the control file to create
  25074.                 for this protocol. Maximus will write text to this control
  25075.                 file indicating the actions that the protocol is to perform
  25076.                 (such as "send file X" or "receive files to directory Y").
  25077.  
  25078.                 The exact text written to this file is controlled by the
  25079.                 DownloadString, UploadString and Type Opus keywords.
  25080.  
  25081.                 If you have a multinode system, ensure that the task number
  25082.                 is included in the name of the control file (using the %K
  25083.                 token). Otherwise, the control file could get overwritten
  25084.                 by another task.
  25085.  
  25086.              DescriptWord <num>
  25087.  
  25088.                 When parsing the upload log created by the protocol, this
  25089.                 keyword defines the "word number" of the description for
  25090.                 the uploaded file.
  25091.  
  25092.                 For each line in the upload log, Maximus will split the
  25093.                 line into a number of words. Maximus will search for the
  25094.                 <num>th word after it finds the UploadKeyword string. Eve-
  25095.                 rything from that word until the end of the string is con-
  25096.                 sidered the description for the uploaded file. If the up-
  25097.                 load log does not include descriptions, you must specify a
  25098.                 value of 0 for <num>.
  25099.  
  25100.                 For example, if the upload log looks like this:
  25101.  
  25102.                 = 10 Sep 14:10:10 FROG Got \upl\docs.zip Maximus docs
  25103.  
  25104.                 DescriptWord should have a value of 2, since the "Maximus
  25105.                 docs" description begins two words after the UploadKeyword
  25106.                 of "Got."
  25107.  
  25108.              DownloadCmd <cmd>
  25109.  
  25110.                 This keyword specifies the command to execute when a user
  25111.                 requests a download using the current protocol.
  25112.  
  25113.                 For an Opus-compatible protocol, the following format must
  25114.                 be used:
  25115.  
  25116.                 DownloadCmd <n>.Exe <n>%K.Ctl -p%p -b%b -t%k -m%d -f%D -r%t
  25117.  
  25118.                 where <n> is the name of the external protocol, such as
  25119.                 "ASCII" or "Kermit."
  25120.  
  25121.  
  25122.  
  25123.              18. Control File Reference                                456
  25124.  
  25125.              DownloadKeyword <keyword>
  25126.  
  25127.                 When parsing the download log created by an external proto-
  25128.                 col, Maximus uses this keyword to identify the log entries
  25129.                 that indicate that the user has downloaded a file.
  25130.  
  25131.                 For example, if the protocol writes out lines in this for-
  25132.                 mat when the user downloads a file (as do Opus-compatible
  25133.                 protocols):
  25134.  
  25135.                 Sent c:\path\filename.zip
  25136.  
  25137.                 you should specify a DownloadKeyword of "Sent." To search
  25138.                 for a string containing spaces, enclose <keyword> in
  25139.                 quotes.
  25140.  
  25141.              DownloadString <cmd>
  25142.  
  25143.                 Maximus will place this string in the protocol control file
  25144.                 when it wishes to send a file to the user.
  25145.  
  25146.                 This line is written to the control file once for each file
  25147.                 selected by the user. If the "%s" token is included in the
  25148.                 command string, it is replaced with the name of the file to
  25149.                 be sent.
  25150.  
  25151.                 For example, with the following definition:
  25152.  
  25153.                 DownloadString Send %s
  25154.  
  25155.                 Maximus will create a protocol control file that contains
  25156.                 entries of the form:
  25157.  
  25158.                 Send d:\file\maxutil\uedit.zip
  25159.                 Send d:\file\netutil\nodelist.zip
  25160.  
  25161.                 For Opus-compatible protocols, use a DownloadString of
  25162.                 "Send %s".
  25163.  
  25164.              End Protocol
  25165.  
  25166.                 This keyword marks the end of a protocol definition.
  25167.  
  25168.              FilenameWord <num>
  25169.  
  25170.                 When parsing the upload log created by the protocol, this
  25171.                 keyword defines the "word number" of the name of the up-
  25172.                 loaded file.
  25173.  
  25174.                 For each line in the upload log, Maximus will split the
  25175.                 line into a number of words. Maximus will search for the
  25176.                 <num>th word after it finds the UploadKeyword string. That
  25177.                 word is the name of the uploaded file.
  25178.  
  25179.  
  25180.  
  25181.              18. Control File Reference                                457
  25182.  
  25183.                 For example, if the upload log looks like this:
  25184.  
  25185.                 = 10 Sep 14:10:10 FROG Got \upl\docs.zip Maximus docs
  25186.  
  25187.                 FilenameWord should have a value of 1, since the
  25188.                 \upl\docs.zip filename begins one word after the UploadKey-
  25189.                 word of "Got."
  25190.  
  25191.              LogFile <filespec>
  25192.  
  25193.                 This keyword defines the name of the log file created by
  25194.                 the external protocol. The "%K" external program transla-
  25195.                 tion character can be used to embed the task number in the
  25196.                 filename.
  25197.  
  25198.                 When the protocol returns, Maximus scans this file for
  25199.                 download and upload file information, as specified by the
  25200.                 DownloadString and UploadString keywords.
  25201.  
  25202.              Protocol <name>
  25203.  
  25204.                 This keyword identifies the beginning of a protocol defini-
  25205.                 tion. The <name> parameter is used to identify the name of
  25206.                 the protocol on the protocol menu. Consequently, the first
  25207.                 character of <name> must be unique.
  25208.  
  25209.              Type Batch
  25210.              Type Bi
  25211.              Type Opus
  25212.  
  25213.                 These modifiers are used to set certain flags for the ex-
  25214.                 ternal protocol.
  25215.  
  25216.                 Zero or more of the optional modifiers from Table 18.14 can
  25217.                 be included:
  25218.  
  25219.                 Table 18.14 Protocol Types
  25220.  
  25221.                 Keyword    Description
  25222.  
  25223.                 Batch      The specified protocol accepts more than one
  25224.                            file at a time. The user is not prompted to en-
  25225.                            ter the names of files to upload.
  25226.                 Bi         The protocol can both send and receive files at
  25227.                            the same time. Maximus scans the protocol log
  25228.                            file for both upload and download entries.
  25229.                 Opus       Maximus should generate Opus-compatible infor-
  25230.                            mation at the beginning of the protocol control
  25231.                            file.
  25232.  
  25233.  
  25234.  
  25235.              18. Control File Reference                                458
  25236.  
  25237.              UploadCmd <cmd>
  25238.  
  25239.                 This keyword specifies the command to execute when a user
  25240.                 requests an upload using the current protocol.
  25241.  
  25242.                 For an Opus-compatible protocol, the following format must
  25243.                 be used:
  25244.  
  25245.                 UploadCmd <n>.Exe <n>%K.Ctl -p%p -b%b -t%k -m%d -f%D -r%t
  25246.  
  25247.                 where <n> is the name of the external protocol, such as
  25248.                 "ASCII" or "Kermit."
  25249.  
  25250.              UploadString <cmd>
  25251.  
  25252.                 This keyword defines the string that Maximus places in the
  25253.                 protocol control file to request that a file be uploaded.
  25254.  
  25255.                 For non-batch protocols, a "%s" in <cmd> translates into
  25256.                 the path and filename of the file to be received.
  25257.  
  25258.                 For batch protocols, a "%s" in <cmd> translates into the
  25259.                 upload directory.
  25260.  
  25261.                 For Opus-compatible protocols, <cmd> should be "Get".
  25262.  
  25263.              UploadKeyword <keyword>
  25264.  
  25265.                 When parsing the upload log created by an external proto-
  25266.                 col, Maximus uses this keyword to identify the log entries
  25267.                 that indicate that the user has uploaded a file.
  25268.  
  25269.                 For example, if the protocol writes out lines in this for-
  25270.                 mat when the user uploads a file (as do Opus-compatible
  25271.                 protocols):
  25272.  
  25273.                 Got c:\path\filename.zip
  25274.  
  25275.                 you should specify a UploadKeyword of "Got." To search for
  25276.                 a string containing spaces, enclose <keyword> in quotes.
  25277.  
  25278.  
  25279.              18.10.2. Examples
  25280.  
  25281.              Sample protocol entries for BiModem, DSZ (Zmodem MobyTurbo),
  25282.              OASCII, OKermit and MPt are contained in the distribution
  25283.              version of the protocol.ctl file. However, these protocol en-
  25284.              tries are commented out by default. To enable a protocol,
  25285.              simply uncomment all of the lines belonging to that protocol.
  25286.  
  25287.              If you are using an Opus-compatible external protocol, the
  25288.              entry in protocol.ctl should have the following format.
  25289.  
  25290.  
  25291.  
  25292.              18. Control File Reference                                459
  25293.  
  25294.              (Replace each instance of <name> with the name of the exter-
  25295.              nal protocol.)
  25296.  
  25297.                 Protocol <name>
  25298.                   Type Batch
  25299.                   Type Opus
  25300.                   LogFile <name>%K.Log
  25301.                   ControlFile <name>%K.Ctl
  25302.                   DownloadCmd <name>.Exe <name>%K.Ctl -p%p -b%b -t%k -m%d -
  25303.                 f%D -%t
  25304.                   UploadCmd <name>.Exe <name>%K.Ctl -p%p -b%b -t%k -m%d -
  25305.                 f%D -r%t
  25306.                   DownloadString Send %s
  25307.                   UploadString Get %s
  25308.                   DownloadKeyword Sent
  25309.                   UploadKeyword Got
  25310.                   FilenameWord 1
  25311.                   DescriptWord 4
  25312.                 End Protocol
  25313.  
  25314.  
  25315.              18.11. Event File
  25316.  
  25317.              Maximus 3.0 includes an internal event file manager. When us-
  25318.              ing Maximus in WFC mode, the event manager can be used to run
  25319.              external programs at predetermined times. The event manager
  25320.              also controls when the Yell command can be used to page the
  25321.              SysOp.
  25322.  
  25323.              All events are defined in an ASCII file named events##.bbs,
  25324.              where ## is the Maximus node number (in hexadecimal). Maximus
  25325.              will automatically compile the ASCII-based event file into a
  25326.              binary events##.dat file when it starts up.
  25327.  
  25328.              By default, Maximus will always load the event file for the
  25329.              node specified by the Task keyword in the control file, or
  25330.              for the node specified using -n on the command line. However,
  25331.              one event file can be used for an entire multinode system as
  25332.              long as the event file contains only yell events. To override
  25333.              the "##" used in events##.bbs, use the -e command line pa-
  25334.              rameter.
  25335.  
  25336.              Every line in the event file has the following format:
  25337.  
  25338.                 Event <day> <start> [end] [flags...]
  25339.  
  25340.              <day> specifies the day on which this event is to be exe-
  25341.              cuted. Valid days are "Sun," "Mon," "Tue," "Wed," "Thu,"
  25342.              "Fri," and "Sat.". To run an event on every day of the week,
  25343.              specify "All." To run an event only on weekdays, specify
  25344.              "WkDay." To run an event only on weekends, specify "WkEnd."
  25345.              To run an event on a combination of days, separate each day
  25346.  
  25347.  
  25348.  
  25349.              18. Control File Reference                                460
  25350.  
  25351.              with a "|".  (For example, "Sun|Mon|Tue" specifies an event
  25352.              that runs on Sunday, Monday and Tuesday.)
  25353.  
  25354.              <start> is the starting time for the event in 24-hour format.
  25355.  
  25356.              [end] is the optional ending time for the event, also in 24-
  25357.              hour format. External events do not require an ending time,
  25358.              but yell events do.
  25359.  
  25360.              Following the starting and ending time are zero or more
  25361.              flags. Any or all of the flags from Table 18.15 can be speci-
  25362.              fied:
  25363.  
  25364.              Table 18.15 Event Flags
  25365.  
  25366.               Flag             Description
  25367.  
  25368.               exit=<erl>       This tells Maximus to exit with an error-
  25369.                                level of <erl> as soon as the event
  25370.                                starts. This flag is valid only when us-
  25371.                                ing WFC mode.
  25372.               bells=<num>      This specifies the number of bells (or
  25373.                                tunes) that Maximus plays when a user
  25374.                                yells during this event. This flag acti-
  25375.                                vates the yell function for the specified
  25376.                                time period.
  25377.               maxyell=<num>    This specifies the maximum number of
  25378.                                times that a user can yell (without the
  25379.                                SysOp answering) during one session.
  25380.               tune=<name>      This specifies the tune to play during
  25381.                                the current event.  <name> can be any
  25382.                                single word up to 32 characters long.
  25383.                                Maximus will search the tunes.bbs file to
  25384.                                find the tune with the specified name.
  25385.  
  25386.                                If no tune is specified, Maximus will
  25387.                                make simple beeping noises. To have Maxi-
  25388.                                mus select a tune at random, use
  25389.                                "tune=random".
  25390.  
  25391.  
  25392.              For example, given the following event line:
  25393.  
  25394.                 Event Wed|Thu|Fri 20:00 23:59 exit=9 bells=3 maxyell=2
  25395.                 tune=StarTrk
  25396.  
  25397.              Maximus exits with errorlevel 9 at the beginning of the
  25398.              event. If a user yells, Maximus plays the "StarTrk" tune
  25399.              (from tunes.bbs) up to 3 times for each yell. The user would
  25400.              be allowed to yell only twice during one session.
  25401.  
  25402.  
  25403.  
  25404.              18. Control File Reference                                461
  25405.  
  25406.              18.12. Language Translation File Reference
  25407.  
  25408.              If you wish to change the language source in english.mad, you
  25409.              should pay attention to these points:
  25410.  
  25411.              *  Ensure that you do not change the order of the statements
  25412.                 within the file. Disaster will result if the strings get
  25413.                 out of order. You can add and delete blank lines or com-
  25414.                 ments, but leave the order of the strings alone.
  25415.  
  25416.              *  After changing the language file source, the file must be
  25417.                 recompiled with MAID to create the .ltf version of the lan-
  25418.                 guage.
  25419.  
  25420.              *  Finally, if you wish to create a modified language for
  25421.                 other people to use, you can simply copy english.* to my-
  25422.                 lang.* (or whatever the new language is to be called). You
  25423.                 can then add a Language Mylang statement in the language
  25424.                 control file.
  25425.  
  25426.              The exact definitions for the strings in the english.mad are
  25427.              version-dependent, so they are not described here. Many of
  25428.              the strings can be changed by simply replacing the text in
  25429.              the string with the appropriate translation.
  25430.  
  25431.              However, for strings that include formatting characters (such
  25432.              as "%s," "%c" and others), ensure that the order of these
  25433.              characters is not modified. The text between the groups of
  25434.              formatting characters can be changed, as long as the format-
  25435.              ting characters remain in the same order relative to each
  25436.              other.
  25437.  
  25438.              In addition, some of the strings in the language file have an
  25439.              implied maximum length. There is no easy way to determine the
  25440.              maximum length of a language file string. However, if you ex-
  25441.              pand one of the language strings by a significant amount and
  25442.              your copy of Maximus no longer works when using that language
  25443.              file, try reducing the length of the string.
  25444.  
  25445.              Finally, you can use the user heap concept to add language
  25446.              file support for MEX programs. User heaps are user-definable
  25447.              language string heaps, similar to the heaps in the system
  25448.              language file, except that they are used exclusively by MEX
  25449.              programs.
  25450.  
  25451.              A user heap is defined in the language file by using a header
  25452.              of the form:
  25453.  
  25454.                 =heapname
  25455.  
  25456.              (This is used instead of the regular heap header of
  25457.              ":heapname".)
  25458.  
  25459.  
  25460.  
  25461.              18. Control File Reference                                462
  25462.  
  25463.              MAID automatically exports user heaps to the language.mh file
  25464.              when it is run. For every language string defined in a user
  25465.              heap, MAID generates a "str_<name>" macro that can be used
  25466.              from within a MEX program to reference the string.
  25467.  
  25468.              To use a user heap from a MEX program, you must:
  25469.  
  25470.              1. create a <heapname>.lh file, containing the "=<heapname>"
  25471.                 header and any strings that you want to place in the heap,
  25472.  
  25473.              2. edit \max\lang\user.lh and add an "#include" directive to
  25474.                 include the .lh file from step 1,
  25475.  
  25476.              3. add a "#define INCL_<heapname>" directive at the top of
  25477.                 your MEX program,
  25478.  
  25479.              4. add a "#include <language.mh>" directive at the top of your
  25480.                 MEX program, just below the #define from step 3, and
  25481.  
  25482.              5. call the function called init_lang_<heapname> from within
  25483.                 your MEX program's main function.
  25484.  
  25485.              Having done this, any of the strings declared in the
  25486.              <heapname>.lh file can be accessed from your MEX program by
  25487.              appending the "str_" prefix to the beginning of the string
  25488.              name.
  25489.  
  25490.        Warni MEX programs that use a user heap must be recompiled if the
  25491.          ng! portion of the language file containing that heap is modi-
  25492.              fied.
  25493.  
  25494.              For an example of user heaps, please see \max\m\mexchat.mex
  25495.              and the associated \max\m\mexchat.lh file.
  25496.  
  25497.  
  25498.  
  25499.  
  25500.  
  25501.  
  25502.  
  25503.  
  25504.                                                                  Appendices
  25505.  
  25506.  
  25507.              Appendix A: Common Problems
  25508.  
  25509.              This section describes some of the common problems that some
  25510.              Maximus SysOps experience:
  25511.  
  25512.  
  25513.     PROBLEM  Users cannot upload QWK messages. Maximus reports "invalid
  25514.              message area" whenever a user tries to upload a message.
  25515.  
  25516.     SOLUTION Maximus needs some way to determine whether or not a user is
  25517.              allowed to upload a message to an area. To do this, it looks
  25518.              for the menu named "MESSAGE" and tries to find a Msg_Upload
  25519.              command on it. Maximus uses the privilege level for this com-
  25520.              mand to determine whether or not the user can access the com-
  25521.              mand.
  25522.  
  25523.              However, if you have renamed your message menu, Maximus will
  25524.              not know where to look and it will not allow users to upload
  25525.              messages. To solve the problem, you can either:
  25526.  
  25527.              *  add a MenuName keyword that specifies the correct message
  25528.                 menu name for all of your message areas, or
  25529.  
  25530.              *  create a menu called "MESSAGE" and add a Msg_Upload option
  25531.                 to it. This menu does not need to be referenced by any
  25532.                 other menus; just as long as the menu is called "MESSAGE,"
  25533.                 Maximus will be able to read the menu and permit QWK
  25534.                 uploads.
  25535.  
  25536.  
  25537.     PROBLEM  Maximus is not adding an origin line or a tear line to mes-
  25538.              sages originating from my system, but this only seems to be
  25539.              happening in certain areas.
  25540.  
  25541.     SOLUTION You probably specified the wrong area type in your message
  25542.              area control file. Ensure that you have included a Style Echo
  25543.              in the message area definition.
  25544.  
  25545.  
  25546.     PROBLEM  When I run an external program, Maximus tries to access one
  25547.              of my CD-ROMs.
  25548.  
  25549.     SOLUTION You forgot to edit the Save Directories definition in the
  25550.              system control file. Before running an external program,
  25551.              Maximus tries to save the current directory for all drives
  25552.              indicated in that statement. If you accidentally specify the
  25553.  
  25554.  
  25555.  
  25556.              Appendices                                                464
  25557.  
  25558.              drive letter for a floppy or CD-ROM drive, Maximus will try
  25559.              to access the disk when it shells out.
  25560.  
  25561.  
  25562.     PROBLEM  When I try to view a file containing ANSI graphics, it comes
  25563.              out garbled and I can see only the text version of the ANSI
  25564.              commands.
  25565.  
  25566.     SOLUTION Do not use ANSI graphics directly. Use the supplied ANS2BBS
  25567.              utility to convert your ANSI screens into a Maximus .bbs
  25568.              file.
  25569.  
  25570.  
  25571.     PROBLEM  When using the AVATAR graphics mode, users report that every-
  25572.              thing has changed colors, the full-screen editor does not
  25573.              work, and other display-related problems.
  25574.  
  25575.     SOLUTION Your user is probably using Telix for DOS. Early versions of
  25576.              Telix have bugs in the AVATAR emulation code.
  25577.  
  25578.  
  25579.     PROBLEM  When a user presses <ctrl-c>, Maximus stops sending output to
  25580.              the user, even though everything still looks fine on the lo-
  25581.              cal console.
  25582.  
  25583.     SOLUTION Turn off the Send Break to Clear Buffer feature in the system
  25584.              control file. Many modems do not support this feature.
  25585.  
  25586.  
  25587.     PROBLEM  Callers sometimes do not see the end of the
  25588.              \max\misc\byebye.bbs file. They report that Maximus hangs up
  25589.              before it finishes displaying the file.
  25590.  
  25591.     SOLUTION Place several [pause] MECCA tokens at the end of
  25592.              \max\misc\byebye.bbs. Modems which have transmit buffers make
  25593.              no effort to empty the buffer before hanging up on remote
  25594.              callers; once Maximus sends the file to the modem, it assumes
  25595.              that the file has also been received by the caller, so it
  25596.              hangs up right away. Adding the pauses gives the modem enough
  25597.              time to display the text to the user.
  25598.  
  25599.  
  25600.  
  25601.              Appendices                                                465
  25602.  
  25603.  
  25604.  
  25605.  
  25606.              Appendix B: Error Messages
  25607.  
  25608.              This section describes some of the common error messages that
  25609.              you may see in the system log file.
  25610.  
  25611.              ANSI sequence found, area XX msg YY
  25612.  
  25613.                 This warning is generated by the Maximus security system.
  25614.                 This warning indicates that it found ANSI codes embedded in
  25615.                 the header of a particular message.
  25616.  
  25617.              Barricade file priv, 'XXX'?
  25618.  
  25619.                 Maximus could not make any sense out of an ACS specified in
  25620.                 a barricade file.
  25621.  
  25622.              Can't find 'XXX'
  25623.  
  25624.                 Maximus expected to find a file in a certain location, but
  25625.                 it was not able to find it in the right place.
  25626.  
  25627.              Can't find barricade file XXX
  25628.  
  25629.                 Maximus could not find the file specified in a Barricade
  25630.                 statement for a message or file area.
  25631.  
  25632.              Can't find class record
  25633.  
  25634.                 Maximus was unable to find the class record (in the access
  25635.                 control file) for a particular user's privilege level.
  25636.                 Check the user's privilege level and ensure that it corre-
  25637.                 sponds to a class entry in the access control file.
  25638.  
  25639.              Can't open 'XXX'
  25640.              Can't read 'XXX'
  25641.              Can't write 'XXX'
  25642.  
  25643.                 These messages indicate that Maximus was looking for a par-
  25644.                 ticular file, but it was unable to open/read/write it.
  25645.                 These messages could also indicate some sort of "disk full"
  25646.                 condition.
  25647.  
  25648.              Err: Lastread ptr xlinked, usr#nnn
  25649.  
  25650.                 A user's last-read pointer has become crosslinked. This
  25651.                 usually indicates that an external utility has damaged your
  25652.                 user file. To fix this problem, run "cvtusr -l".
  25653.  
  25654.  
  25655.  
  25656.              Appendices                                                466
  25657.  
  25658.              Invalid UL path, area X
  25659.  
  25660.                 The upload path specified for area X does not exist.
  25661.  
  25662.              Invalid current pwd 'XXX'
  25663.  
  25664.                 The user tried to change his or her password in the Change
  25665.                 Setup section, but the user failed to correctly enter the
  25666.                 current password.
  25667.  
  25668.              Invalid custom cmd: 'X'
  25669.  
  25670.                 There is an invalid character in a one of the Format
  25671.                 XxxFormat definitions in the system control file. Fix the
  25672.                 sequence and recompile.
  25673.  
  25674.              Invalid outside cmd: 'X'
  25675.  
  25676.                 You attempted to use an invalid character as an external
  25677.                 program translation character. Such sequences are normally
  25678.                 used for external programs or when writing to a file with
  25679.                 the [write] MECCA token.
  25680.  
  25681.              Invalid outside errorlevel
  25682.  
  25683.                 This means that you specified an invalid errorlevel for an
  25684.                 errorlevel exit. Valid errorlevels are 5 through 254 inclu-
  25685.                 sive.
  25686.  
  25687.              MEM:ndir
  25688.              MEM:nmsga
  25689.              MEM:nmsgb
  25690.  
  25691.                 These messages are displayed when Maximus runs out of mem-
  25692.                 ory. In the DOS version of Maximus, give it more conven-
  25693.                 tional memory.
  25694.  
  25695.              Max nest lim. exceeded, XXX aborted
  25696.  
  25697.                 This message is displayed when you have tried to [link] a
  25698.                 .bbs file more than 8 levels deep.
  25699.  
  25700.              No mem for delete buf
  25701.              No mem for lastread scan
  25702.              Not enough mem
  25703.  
  25704.                 These mean that Maximus is short on memory. See MSG:ndir.
  25705.  
  25706.              Null ptr/XXX
  25707.  
  25708.                 A critical error occurred in the Maximus code. Please re-
  25709.                 port this error to Lanius Corporation, along with the cir-
  25710.                 cumstances under which the Null Ptr message was generated.
  25711.  
  25712.  
  25713.  
  25714.              Appendices                                                467
  25715.  
  25716.              OA-MEMOVFL
  25717.  
  25718.                 See MEM:ndir.
  25719.  
  25720.              Unknown option type 'XXX'
  25721.  
  25722.                 Maximus found an invalid menu option number in a menu file.
  25723.                 Try recompiling the menu file.
  25724.  
  25725.              Upload 'ABC.BBS' renamed to 'ABC.BBX'
  25726.  
  25727.                 This means that a user tried to upload a file with an ex-
  25728.                 tension of .bbs. Only users in a class that has the Flags
  25729.                 UploadAny attribute are allowed to upload files with an ex-
  25730.                 tension of .bbs.
  25731.  
  25732.              User gave device/path 'XXX'
  25733.              User supplied path 'XXX'
  25734.  
  25735.                 These messages are generated by the Maximus security system
  25736.                 when a user specifies an explicit path or device.
  25737.  
  25738.                 For example, if the user tries to specify an upload file-
  25739.                 name called c:\max\virus.com, Maximus generates a log entry
  25740.                 of "User supplied path 'c:\max'." Maximus will automati-
  25741.                 cally strip off the path, but this message indicates that a
  25742.                 user may be trying to do devious things.
  25743.  
  25744.  
  25745.  
  25746.              Appendices                                                468
  25747.  
  25748.  
  25749.  
  25750.  
  25751.              Appendix C : Command Line Switches
  25752.  
  25753.              This section describes the format of the Maximus command
  25754.              line. Maximus can be invoked as shown below:
  25755.  
  25756.                 max [prm_name] [switches ...]
  25757.  
  25758.              [prm_name] specifies the optional name of the Maximus parame-
  25759.              ter file to use. By default, Maximus will read the system in-
  25760.              formation from max.prm.
  25761.  
  25762.              [switches] can be zero or more of the following optional com-
  25763.              mand line switches. If no switches are specified, Maximus
  25764.              starts in local mode.
  25765.  
  25766.              Table C.1 lists the command line switches supported by Maxi-
  25767.              mus:
  25768.  
  25769.              Table C.1 Maximus Command Line Switches
  25770.  
  25771.               Switch    Description
  25772.  
  25773.               -b<x>     If used in conjunction with the -w switch, this
  25774.                         specifies the maximum system baud rate. Other-
  25775.                         wise, this switch informs Maximus of the speed
  25776.                         of the incoming caller, as passed on by the
  25777.                         program that answered the phone. See also the
  25778.                         -s switch for information on baud rates and
  25779.                         high-speed modems.
  25780.               -c        Create a user.bbs file. This command is nor-
  25781.                         mally only needed the first time that Maximus
  25782.                         is run. Maximus automatically grants SysOp
  25783.                         privileges to a user who logs on when the -c
  25784.                         switch is used.
  25785.               -e<x>     Use <x> as the decimal "task number" for read-
  25786.                         ing event files. Please see section 18.11 for
  25787.                         more information.
  25788.               -j<x>     "Jam" keystrokes into the keyboard buffer. This
  25789.                         option is useful for automatically logging on
  25790.                         as a user. To imbed spaces in the jam command,
  25791.                         you must enclose the entire parameter in double
  25792.                         quotes.
  25793.                         For example, to automatically log on as "Joe
  25794.                         SysOp":
  25795.  
  25796.                            max -k "-jJoe SysOp;y;Pwd"
  25797.  
  25798.                         The "-j-" modifier can be used to completely
  25799.                         clear the keyboard buffer. This forces Maximus
  25800.                         to display the logo.bbs file, even for local
  25801.  
  25802.  
  25803.  
  25804.              Appendices                                                469
  25805.  
  25806.                         logons.
  25807.               -k        Log on in local mode (default).
  25808.               -l<x>     Write the system log to <x>, instead of the
  25809.                         filename specified in the system control file.
  25810.                         If <x> is blank, no log file is used.
  25811.               -m<x>     Override the Multitasker definition in the sys-
  25812.                         tem control file. The following are acceptable
  25813.                         values for <x>:
  25814.                            d ---DoubleDOS
  25815.                            q ---DESQview
  25816.                            m ---PC-MOS
  25817.                            w ---Windows 3.1 or Windows 95
  25818.                            n ---No multitasker
  25819.               -n<x>     Select the node number for this task. This
  25820.                         overrides the Task definition in the system
  25821.                         control file.
  25822.               -p<x>     Selects the COM port number (or port handle for
  25823.                         OS/2) for the current session.
  25824.               -r        Restart a session that was previously ended us-
  25825.                         ing a Xtern_Erlvl exit. Please see section 6
  25826.                         for more information.
  25827.               -s<x>     Use <x> as the locked baud rate. Maximus will
  25828.                         always communicate with the COM port at the
  25829.                         rate specified here. However, it will continue
  25830.                         to calculate file transfer times using the
  25831.                         value specified for -b.
  25832.               -t<x>     Do not allow the current user to remain on-line
  25833.                         for longer than <x> minutes. This command al-
  25834.                         lows a front end mailer to ensure that a user
  25835.                         does not overrun an internal mailer event.
  25836.               -u        Automatically run the system user editor with-
  25837.               -uq       out logging in. The -u switch runs the user
  25838.                         editor in normal mode; the -uq switch runs the
  25839.                         user editor with hotkeys enabled.
  25840.               -vb       (DOS only.) Selects the Maximus video mode. -vb
  25841.               -vi       enables the BIOS video mode; -vi enables the
  25842.                         IBM video mode.
  25843.               -w        Run in Waiting for Caller mode. Please see sec-
  25844.                         tion 5.1 for more information.
  25845.               -xc       Disable carrier drop detection. Maximus will
  25846.                         not monitor the DCD line to determine if a user
  25847.                         has dropped carrier.
  25848.               -xd       Disable automatic DTR dropping when Maximus
  25849.                         ends. When a user logs off, Maximus simply
  25850.                         sends the Busy string without changing DTR.
  25851.               -xj       Disable the local <alt-j> shell feature from
  25852.                         within Maximus. (However, this does not disable
  25853.                         the <alt-j> sequence from within WFC mode.)
  25854.               -xt       Disable Maximus's internal trap logging fea-
  25855.                         ture. Maximus will pause and display an error
  25856.                         pop-up instead of just logging the crash to the
  25857.                         log file (OS/2 only).
  25858.  
  25859.  
  25860.  
  25861.              Appendices                                                470
  25862.  
  25863.               -xz       Disable the internal Zmodem protocol.
  25864.  
  25865.  
  25866.  
  25867.              Appendices                                                471
  25868.  
  25869.  
  25870.  
  25871.              Appendix D: Local Keystrokes
  25872.  
  25873.              Table D.1 describes the keystrokes that can be used on the
  25874.              SysOp console while a user is on-line.
  25875.  
  25876.              Table D.1 Local Keystrokes
  25877.  
  25878.               Key        Description
  25879.  
  25880.               <esc>      Abort the current SysOp operation. This key
  25881.                          will dismiss a pop-up window, abort a file
  25882.                          transfer, turn off keyboard mode, or exit
  25883.                          chat.
  25884.               <space>    Displays the user's statistics in a pop-up
  25885.                          window.
  25886.               A          Enable local keyboard mode.
  25887.               L          Lock the user's privilege level. The user's
  25888.                          privilege level will be restored when the user
  25889.                          logs off or when you press "U."
  25890.               N          Enable Snoop Mode. Maximus will display output
  25891.                          on the local screen.
  25892.               O          Disable Snoop Mode.
  25893.               S          Set privilege level. This displays a pop-up
  25894.                          window that can be used to adjust the user's
  25895.                          privilege level and keys.
  25896.               U          Restore a user's privilege level after a prior
  25897.                          lock operation.
  25898.               Z          Zero the user's cumulative on-line time for
  25899.                          today. This is useful if the user almost over-
  25900.                          ran the Cume limit for the user class, but if
  25901.                          you still want to allow the user to call back
  25902.                          again later in the day.
  25903.               1..8       Toggle the specified key number. These toggles
  25904.                          only work for keys 1 through 8. See the "S"
  25905.                          keystroke to toggle other keys.
  25906.               +          Promote the user's privilege level to a higher
  25907.                          user class.
  25908.               -          Demote the user's privilege level to a lower
  25909.                          user class.
  25910.               !          Toggles the noise made by the Yell command.
  25911.               =          Display the current user's password. This fea-
  25912.                          ture does not work for users with encrypted
  25913.                          passwords.
  25914.               ?          Display the user's statistics (as with
  25915.                          <space>) and turn off Snoop.
  25916.               <up>       Add one minute to the user's time.
  25917.               <pgup>     Add five minutes to the user's time.
  25918.               <down>     Subtract one minute from the user's time.
  25919.               <pgdn>     Subtract five minutes from the user's time.
  25920.               <alt-c>    Initiate chat mode with the current user. Use
  25921.                          the <esc> key to exit chat mode.
  25922.  
  25923.  
  25924.  
  25925.              Appendices                                                472
  25926.  
  25927.               <alt-j>    Shell to the operating system.
  25928.               <alt-n>    Toggle the "Nerd" setting for the current
  25929.                          user. When the nerd flag is enabled, the
  25930.                          user's yells do not make any noise on the lo-
  25931.                          cal console.
  25932.               <alt-d>    Generate fake line noise and drop carrier on
  25933.                          the user.
  25934.               <ctrl-x>   Immediately disconnect the current user.
  25935.               <Fx>       Pressing a function key while a user is on-
  25936.                          line will display one of the \max\misc\f*.bbs
  25937.                          files. For example, pressing <f1> displays the
  25938.                          f1.bbs file. Similarly, <ctrl-fX>, <shift-fX>
  25939.                          and <alt-fX> will display the related cf*.bbs,
  25940.                          sf*.bbs and af*.bbs files.
  25941.  
  25942.  
  25943.  
  25944.              Appendices                                                473
  25945.  
  25946.  
  25947.              Appendix E: User Editor Keystrokes
  25948.  
  25949.              In addition to the highlighted command letters that appear on
  25950.              the user editor screen, Table E.1 lists a number of other
  25951.              keystrokes supported by the user editor:
  25952.  
  25953.              Table E.1 User Editor Keystrokes
  25954.  
  25955.               Key  Description
  25956.  
  25957.               "    Undo changes. This undoes all changes made to the
  25958.                    current user record.
  25959.               '    Find the next user. This continues a search started
  25960.                    with the "~" key.
  25961.               +    Display the next user.
  25962.               -    Display the previous user.
  25963.               /    Redraw the screen.
  25964.               =    Toggle the display of the user's password. (This op-
  25965.                    tion only works for users with unencrypted pass-
  25966.                    words.)
  25967.               ?    Display help on user editor commands.
  25968.               |    Purge users. This function deletes all users who
  25969.                    have the "deleted" flag set in their user record.
  25970.               ~    Find a user. Maximus prompts you for the name of the
  25971.                    user to find (or a part thereof). Maximus will also
  25972.                    search in the alias and phone number fields.
  25973.               C    Create a user. A new user record is appended to the
  25974.                    end of the user file.
  25975.               D    Toggles the "deleted" flag for the current user. The
  25976.                    user is not actually removed from the user file un-
  25977.                    til you do a purge ("|").
  25978.               J    Jump to the last user in the user file.
  25979.  
  25980.  
  25981.  
  25982.              Appendices                                                474
  25983.  
  25984.  
  25985.              Appendix F: AVATAR Colors
  25986.  
  25987.              This section lists all of the AVATAR color codes that can be
  25988.              used in .bbs files.
  25989.  
  25990.              To use this chart, first look in the left-hand column to find
  25991.              the row with the required foreground color. Next, look across
  25992.              the top of the chart to find the column with the required
  25993.              background color. The color number is at the intersection of
  25994.              the foreground row and the background column.
  25995.  
  25996.  
  25997.  Background  Intensity Black  Blue  Green  Cyan Red   Magenta  Yellow White
  25998.    color
  25999.  
  26000.  
  26001.  
  26002.  Black       low         0     16    32     48   64     80       96    112
  26003.              high        8     24    40     56   72     88      104    120
  26004.  
  26005.  Blue        low         1     17    33     49   65     81       97    113
  26006.              high        9     25    41     57   73     89      105    121
  26007.  
  26008.  Green       low         2     18    34     50   66     82       98    114
  26009.              high        10    26    42     58   74     90      106    122
  26010.  
  26011.  Cyan        low         3     19    35     51   67     83       99    115
  26012.              high        11    27    43     59   75     91      107    123
  26013.  
  26014.  Red         low         4     20    36     52   68     84      100    116
  26015.              high        12    28    44     60   76     92      108    124
  26016.  
  26017.  Magenta     low         5     21    37     53   69     85      101    117
  26018.              high        13    29    45     61   77     93      109    125
  26019.  
  26020.  Yellow      low         6     22    38     54   70     86      102    118
  26021.              high        14    30    46     62   78     94      110    126
  26022.  
  26023.  White       low         7     23    39     55   71     87      103    119
  26024.              high        15    31    47     63   79     95      111    127
  26025.  
  26026.  
  26027.  
  26028.              Appendices                                                475
  26029.  
  26030.  
  26031.  
  26032.              Appendix G: Sample BAT/CMD Files
  26033.  
  26034.              This section illustrates how batch files can be used to inte-
  26035.              grate Maximus with a third-party front end mailer.
  26036.  
  26037.  
  26038.              Sample Waiting for Caller Batch File
  26039.  
  26040.                 echo Off
  26041.                 rem * Insert your time zone here
  26042.                 set TZ=EST05
  26043.  
  26044.                 rem * Load FOSSIL driver
  26045.                 bnu
  26046.  
  26047.                 rem * OS/2 users only:
  26048.                 rem *
  26049.                 rem * Comment out the above call to BNU and uncomment
  26050.                 rem * the following MODE command.  (This command should
  26051.                 rem * all be on one line.)
  26052.                 rem *
  26053.                 rem * mode
  26054.                 com1:38400,n,8,1,,TO=OFF,XON=ON,IDSR=OFF,ODSR=OFF,
  26055.                 rem * OCTS=ON,DTR=ON,RTS=HS
  26056.  
  26057.                 rem * This is where you call Maximus itself.  Change
  26058.                 rem * the '%1' and '%2' as necessary, to make Maximus
  26059.                 rem * work with your mailer.  (OS/2 users should replace
  26060.                 rem * "max" with "maxp".)
  26061.  
  26062.                 :Loop
  26063.                 cd\Max
  26064.                 max -w
  26065.                 if errorlevel 50 goto event
  26066.                 if errorlevel 12 goto scan
  26067.                 if errorlevel 11 goto pack
  26068.                 if errorlevel  5 goto after
  26069.                 if errorlevel  4 goto error
  26070.                 if errorlevel  3 goto error
  26071.                 if errorlevel  2 goto after
  26072.                 if errorlevel  1 goto done
  26073.                 goto after
  26074.  
  26075.                 :event
  26076.                 rem * Run external maintenance program here.
  26077.                 goto Loop
  26078.  
  26079.                 :scan
  26080.                 rem * This command should invoke your scanner. For example:
  26081.  
  26082.                 squish out squash -fEchoToss.Log
  26083.  
  26084.  
  26085.  
  26086.              Appendices                                                476
  26087.  
  26088.                 scanbld user.bbs area.dat local matrix @echotoss.log
  26089.                 goto loop
  26090.  
  26091.                 :pack
  26092.                 rem * This should invoke your mail packer.  For example:
  26093.  
  26094.                 squish squash
  26095.                 scanbld user.bbs area.dat local matrix
  26096.  
  26097.                 rem * (OS/2 users should replace "squish" with "squishp"
  26098.                 rem * and "scanbld" with "scanbldp".)
  26099.                 goto Loop
  26100.  
  26101.                 :after
  26102.                 rem * Insert after-caller utilities here.
  26103.                 goto Loop
  26104.  
  26105.                 :error
  26106.                 ECHO A fatal error occurred!
  26107.  
  26108.                 :done
  26109.                 ECHO Maximus down
  26110.                 exit
  26111.  
  26112.              Sample FrontDoor Batch File
  26113.  
  26114.                 echo off
  26115.                 REM * Insert your time zone here
  26116.                 SET TZ=EST5
  26117.  
  26118.                 rem * Load FOSSIL driver
  26119.                 bnu
  26120.  
  26121.                 :loop
  26122.                 cd\FD
  26123.                 FD
  26124.                 if errorlevel 100 goto Local
  26125.                 if errorlevel 40  goto Maint
  26126.                 if errorlevel 34  goto UnpackMail
  26127.                 if errorlevel 33  goto B2400
  26128.                 if errorlevel 32  goto B1200
  26129.                 if errorlevel 31  goto B300
  26130.                 if errorlevel 10  goto Done
  26131.                 goto loop
  26132.  
  26133.                 :Local
  26134.                 rem * A local log-on to Maximus
  26135.                 cd \Max
  26136.                 Max -k
  26137.                 goto after_Max
  26138.  
  26139.                 :B2400
  26140.                 cd \Max
  26141.  
  26142.  
  26143.  
  26144.              Appendices                                                477
  26145.  
  26146.                 Max -b2400 -p1
  26147.                 goto After_Max
  26148.  
  26149.                 :B1200
  26150.                 cd \Max
  26151.                 Max -b1200 -p1
  26152.                 goto After_Max
  26153.  
  26154.                 :B300
  26155.                 cd \Max
  26156.                 Max -b300 -p1
  26157.                 goto After_Max
  26158.  
  26159.                 :After_Max
  26160.                 if errorlevel 12 goto scan
  26161.                 if errorlevel 11 goto pack
  26162.                 scanbld user.bbs area.dat local
  26163.                 goto loop
  26164.  
  26165.                 :unpackmail
  26166.                 rem * This should invoke your mail unpacker.
  26167.  
  26168.                 squish in out squash link -fEchoToss.Log
  26169.                 scanbld user.bbs area.dat @echotoss.log matrix
  26170.                 goto Loop
  26171.  
  26172.                 :scan
  26173.                 rem * This should invoke your mail scanner.
  26174.  
  26175.                 squish out squash -fechotoss.log
  26176.                 scanbld user.bbs area.dat local matrix @echotoss.log
  26177.                 goto loop
  26178.  
  26179.                 :pack
  26180.                 rem * This should invoke your mail packer.
  26181.  
  26182.                 squish squash
  26183.                 scanbld user.bbs area.dat local matrix
  26184.  
  26185.                 goto Loop
  26186.  
  26187.                 :maint
  26188.                 rem * Daily maintenance routine goes here
  26189.                 goto Loop
  26190.                 :done
  26191.                 ECHO FrontDoor ... down
  26192.                 exit
  26193.  
  26194.              Sample BinkleyTerm Batch File
  26195.  
  26196.                 echo off
  26197.                 rem * Insert your time zone here!
  26198.                 Set TZ=EDT5
  26199.  
  26200.  
  26201.  
  26202.              Appendices                                                478
  26203.  
  26204.  
  26205.  
  26206.                 :Top
  26207.  
  26208.                 rem * Unload and reload the FOSSIL driver and video FOSSIL.
  26209.                 rem * The following four lines can be omitted under OS/2.
  26210.  
  26211.                 VFOS_DEL
  26212.                 BNU -U
  26213.                 BNU
  26214.                 VFOS_BIO
  26215.  
  26216.                 rem * Start BinkleyTerm.  Under OS/2, use "BTP unattended
  26217.                 rem * share" to ensure that the com port handle is properly
  26218.                 rem * passed to Maximus.
  26219.  
  26220.                 BT unattended
  26221.                 If ErrorLevel 255 goto Top
  26222.                 If ErrorLevel  96 goto BBS      ; 9600 bps
  26223.                 If ErrorLevel  54 goto BBS      ; 19200 bps
  26224.                 If ErrorLevel  30 goto Mail     ; Incoming ARCmail/pkt/file
  26225.                 If ErrorLevel  24 goto BBS      ; 2400 bps
  26226.                 If ErrorLevel  14 goto Maint    ; Daily maintenance routine
  26227.                 If ErrorLevel  12 goto BBS      ; 1200 bps
  26228.                 If ErrorLevel   3 goto BBS      ; 300 bps
  26229.                 If ErrorLevel   2 goto Top
  26230.                 If ErrorLevel   1 goto End
  26231.  
  26232.                 :Mail
  26233.                 rem * Execute TOSS or IMPORT function here
  26234.  
  26235.                 squish in out squash link -fechotoss.log
  26236.                 scanbld user.bbs area.dat matrix @echotoss.log
  26237.                 goto Top
  26238.  
  26239.                 :Scan
  26240.                 rem * Execute SCAN and PACK functions here
  26241.  
  26242.                 squish out squash -fechotoss.log
  26243.                 scanbld user.bbs area.dat local matrix @echotoss.log
  26244.                 goto Top
  26245.  
  26246.                 :Pack
  26247.                 rem * Execute PACK functions here
  26248.  
  26249.                 squish squash
  26250.                 scanbld user.bbs area.dat local matrix
  26251.                 goto Top
  26252.  
  26253.                 :Maint
  26254.                 rem * Insert daily maintenance routine here
  26255.                 Goto Top
  26256.  
  26257.  
  26258.  
  26259.              Appendices                                                479
  26260.  
  26261.                 :BBS
  26262.                 rem * A human caller is here and wants into the BBS. Bink
  26263.                 rem * will create BBSBATCH.BAT/CMD which calls
  26264.                 SPAWNBBS.BAT/CMD
  26265.                 rem * with the proper parameters, such as speed, time until
  26266.                 rem * next event, and port number).  Maximus is invoked
  26267.                 rem * from SPAWNBBS.
  26268.  
  26269.                 c:
  26270.                 cd \binkley
  26271.                 bbsbatch
  26272.                 goto top
  26273.  
  26274.                 :End
  26275.                 rem * I exited Bink and back to DOS.
  26276.                 c:
  26277.                 cd \binkley
  26278.                 echo Binkley ... Down
  26279.  
  26280.              Sample BinkleyTerm SPAWNBBS.BAT
  26281.  
  26282.                 echo OFF
  26283.                 cd \Max
  26284.  
  26285.                 rem * If running Max at a locked port rate, add a
  26286.                 rem * -s<speed> to the following command.  For example,
  26287.                 rem * to lock the port at 38.4kbps, the following statement
  26288.                 rem * could be used:  "max -b%2 -p%3 -t%4 -s38400".  OS/2
  26289.                 rem * users should do the same, but use "maxp" instead of
  26290.                 rem * "max".
  26291.  
  26292.                 max -b%2 -p%3 -t%4
  26293.  
  26294.                 :ELoop
  26295.                 If ErrorLevel 255 goto End
  26296.                 If ErrorLevel 65  goto Outside
  26297.                 If ErrorLevel 12  goto Export
  26298.                 If ErrorLevel 11  goto Mash
  26299.                 If ErrorLevel 10  goto End
  26300.                 If ErrorLevel 5   goto Acall
  26301.                 goto End
  26302.  
  26303.                 :Outside
  26304.                 call ERRORLVL.BAT
  26305.                 Max -r
  26306.                 goto ELoop
  26307.  
  26308.                 :Export
  26309.                 squish out squash -fechotoss.log
  26310.                 scanbld user.bbs area.dat local matrix @echotoss.log
  26311.                 goto end
  26312.  
  26313.                 :Mash
  26314.  
  26315.  
  26316.  
  26317.              Appendices                                                480
  26318.  
  26319.                 squish squash -fechotoss.log
  26320.                 scanbld user.bbs area.dat local matrix
  26321.                 goto end
  26322.  
  26323.                 :Acall
  26324.                 scanbld user.bbs area.dat local
  26325.                 goto end
  26326.  
  26327.                 :end
  26328.  
  26329.  
  26330.  
  26331.              Appendices                                                481
  26332.  
  26333.  
  26334.  
  26335.              Appendix H: Support Files
  26336.  
  26337.              Table H.2 lists some of the hardcoded filenames that are used
  26338.              by Maximus:
  26339.  
  26340.              Table H.2 Hardcoded Filenames
  26341.  
  26342.               Filename         Description
  26343.  
  26344.               <area>.dsc       This file will be displayed to a user
  26345.                                when entering an area, but only if the
  26346.                                user's lastread pointer is set to 0. (For
  26347.                                Squish areas only.)
  26348.               <area>.sqr       This file is displayed to users every
  26349.                                time they enter a message area. (For
  26350.                                Squish areas only.)
  26351.               <areaname>.sqx   This file is displayed to a user who at-
  26352.                                tempts to enter a message in a read-only
  26353.                                area. (Squish areas only.)
  26354.               active##.bbs     This file is created by Maximus whenever
  26355.                                a user logs onto node "##". The file is
  26356.                                deleted when the user logs off.
  26357.               attrib.bbs       This file is displayed to users who press
  26358.                                a "?" at the attribute prompt in the
  26359.                                full-screen message entry header.
  26360.               baduser.bbs      Maximus will use this file (in the main
  26361.                                system directory) to screen out unwanted
  26362.                                names for new user logons. Maximus will
  26363.                                display the \max\misc\bad_user.bbs file
  26364.                                if a user attempts to use a name defined
  26365.                                in this file. This file is a straight AS-
  26366.                                CII list of names not to be allowed on
  26367.                                the BBS, one name to a line. Each name in
  26368.                                the file is matched to either the first,
  26369.                                last, or the entire name of the user. (If
  26370.                                the first character of the string in
  26371.                                baduser.bbs is a "~", Maximus will per-
  26372.                                form a substring search.)
  26373.               blt-1.1,         Bulletins to be placed in QWK mail pack-
  26374.               blt-1.99         ets. These files should be placed in the
  26375.                                \max\olr directory.
  26376.               browse.bbs       The help file for the Msg_Browse command.
  26377.               chathelp.bbs     The help file for the multinode chat.
  26378.               chatpage.bbs     The file displayed to the user when a
  26379.                                chat request is received from another
  26380.                                node.
  26381.               chg_sent.bbs     The file displayed when a user tries to
  26382.                                edit a message which has already been
  26383.                                sent, packed, or scanned out.
  26384.               chg_no.bbs       The file displayed when a user tries to
  26385.                                change a message which was written by
  26386.  
  26387.  
  26388.  
  26389.              Appendices                                                482
  26390.  
  26391.                                someone else.
  26392.               descript.bbs     This file is displayed to users who have
  26393.                                a lastread pointer of 0 when they enter
  26394.                                the message area containing this file.
  26395.                                (For *.MSG areas only.)
  26396.               excbytes.bbs     This file is displayed to users who at-
  26397.                                tempt to download too many kilobytes in
  26398.                                one session.
  26399.               excratio.bbs     This file is displayed to users who at-
  26400.                                tempted to download a file that would ex-
  26401.                                ceed the file download ratio.
  26402.               exctime.bbs      This file is displayed to users who at-
  26403.                                tempted to download a file that would ex-
  26404.                                ceed the time limit.
  26405.               file_bad.bbs     This file is displayed when an uploaded
  26406.                                file fails the upload virus check. For
  26407.                                more information, see Upload Check Virus
  26408.                                in the system control file.
  26409.               file_ok.bbs      This file is displayed when an uploaded
  26410.                                file passes the upload virus check. For
  26411.                                more information, see Upload Check Virus
  26412.                                in the system control file.
  26413.               goodbye          The file displayed to QWK users when they
  26414.                                close the mail packet from your system.
  26415.                                This file should be in the \max\olr di-
  26416.                                rectory.
  26417.               hello            The file displayed to QWK users as they
  26418.                                open the mail packet from your system.
  26419.                                This file should be in the \max\olr di-
  26420.                                rectory.
  26421.               maxfiles.idx     This is the system-wide file index (as
  26422.                                created by FB).
  26423.               mtag.dat         This is a binary file used by Maximus to
  26424.                                store message area tagging information
  26425.               names.max        This file contains a list of aliases to
  26426.                                be used when entering NetMail messages.
  26427.                                This file must be in the \max directory.
  26428.                                Each line has the following format:
  26429.  
  26430.                                <alias>,<name>,<addr> [,<subj>]
  26431.  
  26432.                                When Maximus spots a message addressed to
  26433.                                <alias>, the message will be automati-
  26434.                                cally readdressed to <name> with a desti-
  26435.                                nation address of <addr>. The optional
  26436.                                <subject> can be used to enter the de-
  26437.                                fault for the message subject field. If a
  26438.                                "*" is placed in front of <alias>, the
  26439.                                alias definition can only be accessed by
  26440.                                users in a class with the MailFlags
  26441.                                MsgAttrAny attribute.
  26442.               newfiles.dat     This file is displayed to QWK users when
  26443.                                the user requests a listing of new files.
  26444.  
  26445.  
  26446.  
  26447.              Appendices                                                483
  26448.  
  26449.                                This file should be placed in the
  26450.                                \max\olr directory.
  26451.               news             This file is displayed to a QWK user when
  26452.                                the user requests the news file. This
  26453.                                file should be placed in the \max\olr di-
  26454.                                rectory.
  26455.               notin.bbs        Maximus displays this file when a user
  26456.                                yells for the SysOp and the SysOp does
  26457.                                not respond. This file should be in the
  26458.                                \max\misc directory.
  26459.               rawdir.bbs       If this file is placed in the Download
  26460.                                path for a file area, it is automatically
  26461.                                displayed to the user before the output
  26462.                                of the File_Raw command.
  26463.               readonly.bbs     If this file exists in the directory for
  26464.                                a read-only *.MSG message area, Maximus
  26465.                                will display this file when the user at-
  26466.                                tempts to enter a message.
  26467.               rules.bbs        If this file exists in the directory for
  26468.                                a *.MSG area, Maximus will display it
  26469.                                file to all callers who enter the area.
  26470.               tag_file.bbs     This is the help file for the File_Tag
  26471.                                command.
  26472.               tag_msg.bbs      This is the help file for the Msg_Tag
  26473.                                command.
  26474.               timeup.bbs       This file is displayed to a user whose
  26475.                                time limit has expired.
  26476.               why_ansi.bbs     This is the help file for the "ANSI
  26477.                                graphics [Y,n,?]" question.
  26478.               why_fb.bbs       This is the help file for the "Leave a
  26479.                                message to the SysOp [Y,n,?]" question.
  26480.               why_fsed.bbs     This is the help file for the "Use MaxEd
  26481.                                [Y,n,?]" question.
  26482.               why_hot.bbs      This is the help file for the "Use Hot-
  26483.                                keys [Y,n,?]" question.
  26484.               why_hu.bbs       This is the help file for the "Goodbye
  26485.                                [Y,n,?]" question.
  26486.               why_pc.bbs       This is the help file for the "Use IBM
  26487.                                Chars [Y,n,?]" question.
  26488.               why_pvt.bbs      This is the help file for the "Private
  26489.                                [Y,n]?" question when entering a message
  26490.                                in TTY mode.
  26491.               xpdate.bbs       This file is displayed when a user's sub-
  26492.                                scription expires by date. This file is
  26493.                                in the \max\misc directory.
  26494.               xptime.bbs       This file is displayed when a user's sub-
  26495.                                scription expires by time. This file is
  26496.                                in the \max\misc directory.
  26497.               yell.bbs         Maximus will display this file (from the
  26498.                                \max\misc directory) if a user tries to
  26499.                                yell when yell is turned off.
  26500.  
  26501.  
  26502.  
  26503.  
  26504.  
  26505.  
  26506.  
  26507.  
  26508.                                                                       Index
  26509.  
  26510.                                                  OldPriv, 453
  26511.                   *                              RatioFree, 451, 453
  26512.              *.MSG, 49, 65, 428                  Time, 451, 454
  26513.                                                  UploadReward, 454
  26514.                   9                              UserFlags, 454
  26515.              9600 bps, 34, 37, 371               XferBaud, 420, 454
  26516.                                               ACS, 60, 61, 69, 79, 90, 98,
  26517.                   A                             101, 317, 369, 424, 425,
  26518.              ACCEM, 125, 126                    426, 430, 431, 432, 438,
  26519.              access control file. See ac-       465
  26520.               cess.ctl                        Address, 395
  26521.              access control string. See       alias, 25
  26522.               ACS                             ANS2BBS, 126, 127
  26523.              access.ctl                       ANS2MEC, 126, 127
  26524.                 Access, 451                   ANSI, 6, 7, 12, 17, 19, 26,
  26525.                 Calls, 451                      41, 64, 88, 89, 110, 112,
  26526.                 Cume, 451, 471                  114, 126, 127, 128, 138,
  26527.                 Desc, 451                       153, 157, 238, 256, 270,
  26528.                 End Access, 451                 271, 272, 358, 371, 376,
  26529.                 FileLimit, 451                  401, 417, 440, 441, 464,
  26530.                 FileRatio, 451, 453             465, 483
  26531.                 Flags, 451                    ARC, 443
  26532.                 Flags DloadHidden, 452        ARCTIC, 35
  26533.                 Flags Hangup, 452             arrow keys
  26534.                 Flags Hide, 441, 450, 452        using menu options with,
  26535.                 Flags NoFileLimit, 452            438
  26536.                 Flags NoLimits, 452           AUTOEXEC.BAT, 36, 120, 138
  26537.                 Flags NoTimeLimit, 452        AVATAR, 7, 12, 17, 19, 26,
  26538.                 Flags ShowAllFiles, 452         64, 88, 110, 114, 138,
  26539.                 Flags ShowHidden, 452           153, 237, 238, 256, 270,
  26540.                 Flags UploadAny, 452, 467       358, 361, 371, 376, 417,
  26541.                 Key, 452                        435, 440, 441, 464, 474
  26542.                 Level, 451, 452
  26543.                 LoginFile, 452                     B
  26544.                 LogonBaud, 411, 419, 452      barricade, 77, 78, 253, 254,
  26545.                 MailFlags, 453                  424, 430, 465
  26546.                 MailFlags Editor, 409,           extended, 78
  26547.                  453                          batch files
  26548.                 MailFlags LocalEditor,           errorlevel, 107
  26549.                  409, 453                     BinkleyTerm, 44, 478
  26550.                 MailFlags MsgAttrAny,         BNU, 2, 35, 36, 50, 475, 478
  26551.                  410, 446, 453, 482           BORED, 17, 19, 26, 156, 311,
  26552.                 MailFlags NetFree, 453          416
  26553.                 MailFlags NoRealName, 453     BUFFERS=, 38
  26554.                 MailFlags ShowPvt, 10,
  26555.                  447, 453                          C
  26556.                 MailFlags WriteRdOnly,        cable, 34
  26557.                  10, 429, 453                 callinfo.bbs, 112, 113
  26558.  
  26559.  
  26560.  
  26561.              Index                                                     486
  26562.  
  26563.              CB chat, 122, 123                display files. See MECCA,
  26564.              CD-ROM, 73, 74, 75, 76, 131,       files
  26565.               412, 431, 432, 433, 463         Display_Menu, 442
  26566.              chain.txt, 112, 113              door. See external program
  26567.              characters                       door interface, 112, 113
  26568.                 high-bit, 26                  door.sys, 112, 113
  26569.              chat, 2, 9, 28, 29, 54, 117,     doors
  26570.               120, 121, 122, 123, 143,           OS/2 and, 28
  26571.               161, 261, 269, 270, 275,        dorinfo1.def, 112
  26572.               341, 379, 390, 399, 401,        DoubleDOS, 389, 469
  26573.               417, 423, 439, 446, 471,        download, 22, 27, 29, 430,
  26574.               481                               444
  26575.              colors control file. See         downloads
  26576.               colors.ctl                         free, 71
  26577.              colors.ctl                          staged, 73
  26578.                 Popup Border, 422             DTR, 393, 469
  26579.                 Popup highlight, 422          duplicate file checking, 414
  26580.                 Popup List, 422
  26581.                 Popup LSelect, 422                 E
  26582.                 Popup Text, 422               EchoMail areas, 10
  26583.                 Status Bar, 422               EDITCAL, 129
  26584.                 Status Chat, 423              editor
  26585.                 Status Key, 423                  ASCII, 38, 39, 63, 71, 80
  26586.                 WFC Activity, 423             EMS
  26587.                 WFC ActivityBor, 423             swapping to, 391
  26588.                 WFC Keys, 423                 english.mad, 132, 133, 461
  26589.                 WFC KeysBor, 423              errorlevel, 45, 46, 47, 48,
  26590.                 WFC Line, 423                   50, 54, 86, 106, 107, 108,
  26591.                 WFC Modem, 423                  109, 140, 141, 396, 399,
  26592.                 WFC ModemBor, 423               450, 460, 466, 475, 476,
  26593.                 WFC Name, 423                   477
  26594.                 WFC Status, 424               events
  26595.                 WFC StatusBor, 424               external, 53
  26596.              colors.lh, 422                      yell, 53, 54
  26597.              COM.SYS, 35                      exebbs.bat, 44
  26598.              COM16550.SYS, 35                 expiration. See subscription
  26599.              compress.cfg, 400, 421           expiration date, 94, 362
  26600.              conference areas, 10             extended ASCII, 26, 156,
  26601.              CONFIG.SYS, 36, 38, 123, 138       429, 440
  26602.              control.dat, 422                 extended barricades, 78
  26603.              credit. See NetMail, credit      external program, 8, 15, 17,
  26604.              custom menu, 79, 80, 81,           22, 28, 42, 45, 49, 53,
  26605.               374, 436                          83, 105, 106, 107, 109,
  26606.              CVTUSR, 41, 127, 128               111, 112, 113, 114, 134,
  26607.                                                 135, 239, 263, 264, 278,
  26608.                   D                             327, 355, 366, 367, 368,
  26609.              data carrier detect. See DCD       382, 385, 387, 388, 391,
  26610.              DCD, 33, 34, 266, 275, 283,        401, 404, 412, 417, 419,
  26611.               284, 469                          437, 442, 450, 457, 459,
  26612.              DESQview, 117, 389, 469            463, 466
  26613.              DigiBoard, 35
  26614.              DIP switches, 33                      F
  26615.                                               farea.dat, 40
  26616.  
  26617.  
  26618.  
  26619.              Index                                                     487
  26620.  
  26621.              FB, 23, 75, 76, 77, 129,         flow control
  26622.               131, 414, 431, 432, 482            CTS, 394
  26623.              FidoNet, 10, 42, 44, 120,           DSR, 394
  26624.               395, 396, 398                      XON, 394
  26625.              file area control file. See      FOSSIL, 2, 35, 36, 49, 113,
  26626.               filearea.ctl                      391, 394, 475, 476, 478
  26627.              file areas, 39, 64, 66           FrontDoor, 44, 398, 477
  26628.                 hierarchical, 68              FSR, 27
  26629.                 overriding, 24                function keys
  26630.                 searching, 21                    using menu options with,
  26631.              file attach, 12, 86, 87, 88,         438
  26632.               253, 375, 390, 400, 401,
  26633.               408, 424, 428, 447                   G
  26634.              filearea.ctl, 40                 GAP, 112
  26635.                 ACS, 430                      goto, 47, 48, 50, 51, 476,
  26636.                 Barricade, 77, 430, 465         477, 478, 479, 480
  26637.                 Desc, 406, 430                guest account, 7
  26638.                 Description, 430
  26639.                 Download, 67, 70, 74,              H
  26640.                  430, 432, 483                Hayes, 3, 33, 43, 85, 392
  26641.                 End FileArea, 430             HeaderFile, 434
  26642.                 FileArea, 66, 69, 73, 430     help levels, 25
  26643.                 FileDivisionBegin, 69,
  26644.                  431                               I
  26645.                 FileDivisionEnd, 69, 431      install.exe, 32
  26646.                 FileList, 74, 111, 131,       installation, 2, 31, 32, 36,
  26647.                  431                            40, 41, 48, 51, 118, 120,
  26648.                 MenuName, 431                   121, 151, 387
  26649.                 Override, 432
  26650.                 Type, 432                          K
  26651.                 Type CD, 73, 432              Kermit, 454, 455, 458
  26652.                 Type DateAuto, 75, 403,
  26653.                  432                               L
  26654.                 Type DateList, 75, 76,        label, 46, 47, 48, 50, 51,
  26655.                  129, 403, 432                  108, 125, 192, 246, 247,
  26656.                 Type DateManual, 403, 432       356, 357, 372, 374
  26657.                 Type FileList, 130            language, 27
  26658.                 Type Free, 432                language control file. See
  26659.                 Type FreeBytes, 432             language.ctl
  26660.                 Type FreeSize, 432, 433       language.ctl, 83, 420
  26661.                 Type Hidden, 289, 407,           Language, 420, 461
  26662.                  412, 433                     lastread, 14, 110, 128, 137,
  26663.                 Type NoNew, 433                 145, 147, 150, 151, 155,
  26664.                 Type Slow, 433                  255, 344, 466, 481, 482
  26665.                 Type Staged, 412, 433         lastread pointer
  26666.                 Upload, 67, 433                  crosslinked, 128, 465
  26667.              files                            LIBPATH, 145
  26668.                 deleting, 24                  locked port, 37
  26669.                 downloading, 22               logo.bbs, 468
  26670.                 moving, 24                    LZH, 443
  26671.                 tagging, 22, 23
  26672.              files.bbs, 74, 254, 431, 444          M
  26673.              FILES=, 38                       MAID, 132
  26674.  
  26675.  
  26676.  
  26677.              Index                                                     488
  26678.  
  26679.              mailchecker, 138, 410, 447          Format Time, 407
  26680.              mailer, 44, 49, 51, 108,            Gate NetMail, 396
  26681.               115, 120, 390, 469, 475            Highest FileArea, 407
  26682.              marea.dat, 40                       Highest MsgArea, 408
  26683.              Master Control Program. See         Init, 85, 393
  26684.               MCP                                Input Timeout, 408
  26685.              matrix                              Kill Attach, 87, 408
  26686.                 See Net, NetMail, 436            Kill Private, 408
  26687.              max.ctl, 40, 167                    Local Input Timeout, 409
  26688.                 Address, 395                     Log EchoMail, 10, 66,
  26689.                 After Call, 399                   396, 430
  26690.                 After EchoMail, 396              Log File, 388
  26691.                 After Edit, 396                  Log Mode, 388
  26692.                 After Local, 396                 Logon Level, 7, 56, 409
  26693.                 Alias System, 253, 399,          Logon Preregistered, 409
  26694.                  400                             Logon TimeLimit, 410
  26695.                 Answer, 85, 392, 393, 395        Mailchecker Kill, 410
  26696.                 Area Change Keys, 400            Mailchecker Reply, 410
  26697.                 Ask Alias, 399, 400              Mask Carrier, 394
  26698.                 Ask Phone, 400                   Mask Handshaking, 394
  26699.                 Attach Archiver, 87, 400         MaxMsgSize, 410
  26700.                 Attach Base, 400                 MCP Pipe, 123, 124, 143,
  26701.                 Attach Path, 86, 401              389
  26702.                 Baud Maximum, 393                MCP Sessions, 123, 389
  26703.                 Busy, 392, 393, 469              Menu Path, 410
  26704.                 Charset Chinese, 401             Message Edit, 16, 87, 397
  26705.                 Charset Swedish, 401             Message Send Unlisted,
  26706.                 Chat Capture, 401                 397, 398
  26707.                 Comment Area, 8, 15, 22,         Message Show, 103, 397
  26708.                  65, 402, 446                    MessageData, 411
  26709.                 Connect, 393                     Min Logon Baud, 411, 419
  26710.                 ContentsHelp, 416                Min NonTTY Baud, 411
  26711.                 Dos Close Standard Files,        Min RIP Baud, 411
  26712.                  387                             Multitasker, 389, 469
  26713.                 Edit Disable, 402                Name, 389
  26714.                 FidoUser, 396                    No Critical Handler, 394
  26715.                 File Access, 388                 No Password Encryption,
  26716.                 File Callers, 273, 388            41, 389
  26717.                 File Date, 402                   No RealName Kludge, 411,
  26718.                 File Date Automatic, 71           429
  26719.                 File Password, 388               No SHARE.EXE, 389
  26720.                 FileData, 402                    Nodelist Version, 398
  26721.                 FileList Margin, 403             Output, 394
  26722.                 First File Area, 404             Path Inbound, 88, 390
  26723.                 First Menu, 83, 404              Path IPC, 121, 390
  26724.                 First Message Area, 404          Path Language, 390, 420
  26725.                 Format Date, 404, 407            Path Misc, 390
  26726.                 Format FileFooter, 405           Path NetInfo, 398
  26727.                 Format FileFormat, 405           Path Output, 390
  26728.                 Format FileHeader, 405           Path System, 390
  26729.                 Format MsgFooter, 405            Path Temp, 391
  26730.                 Format MsgFormat, 405            Reboot, 391
  26731.                 Format MsgHeader, 405            Ring, 392, 395
  26732.  
  26733.  
  26734.  
  26735.              Index                                                     489
  26736.  
  26737.                 RIP Path, 379, 411               Uses NoSpace, 415, 418
  26738.                 Save Directories, 73,            Uses NotFound, 418
  26739.                  412, 463                        Uses ProtocolDump, 418
  26740.                 Send Break to Clear              Uses Quote, 384, 418
  26741.                  Buffer, 395, 464                Uses ReplaceHelp, 419
  26742.                 Single Word Names, 5, 412        Uses Returning, 419
  26743.                 Snoop, 391                       Uses Rookie, 419
  26744.                 Stage Path, 73, 412, 433         Uses Shell_Leaving, 419
  26745.                 StatusLine, 412                  Uses Shell_Returning, 419
  26746.                 Strict Time Limit, 412           Uses TimeWarn, 419
  26747.                 Swap, 106, 391                   Uses TooSlow, 419
  26748.                 SysOp, 391                       Uses Tunes, 419
  26749.                 Task, 391, 459, 469              Uses Welcome, 418, 419
  26750.                 Track Base, 413                  Uses XferBaud, 420
  26751.                 Track Exclude, 413               Video, 392
  26752.                 Track Modify, 100, 413           Yell, 9
  26753.                 Track View, 96, 413              Yell Off, 420
  26754.                 Upload Check Dupe, 73,        max.prm, 38, 39, 40, 269,
  26755.                  414                            468
  26756.                 Upload Check Dupe Exten-      MaxEd, 17, 18, 19, 26, 41,
  26757.                  sion, 414                      156, 157, 256, 311, 374,
  26758.                 Upload Check Virus, 414,        402, 409, 418, 440, 442,
  26759.                  482                            483
  26760.                 Upload Log, 415               MaxPipe, 28, 134
  26761.                 Upload Space Free, 415,       maxuapi.dll, 145
  26762.                  418                          MCP, 121, 123, 142, 389
  26763.                 Use UMSGIDs, 420              MECCA, 62, 63, 64, 83, 88,
  26764.                 Uses Application, 409,          93, 94, 105, 106, 109,
  26765.                  410, 415                       112, 113, 114, 125, 126,
  26766.                 Uses BadLogon, 416              127, 135, 161, 162, 167,
  26767.                 Uses Barricade, 77, 78,         355, 356, 357, 358, 359,
  26768.                  416                            360, 368, 371, 378, 381,
  26769.                 Uses BeginChat, 416             382, 383, 391, 402, 418,
  26770.                 Uses BOREDHelp, 416             444, 447, 452, 464, 466
  26771.                 Uses ByeBye, 416                 compiler, 63
  26772.                 Uses Cant_Enter_Area, 416        files, 62
  26773.                 Uses Configure, 416           MECCA token, 63, 94, 106,
  26774.                 Uses DayLimit, 417              109, 112, 114, 126, 167,
  26775.                 Uses EndChat, 417               355, 356, 357, 378, 381,
  26776.                 Uses EntryHelp, 417             452
  26777.                 Uses FileAreas, 67, 362,         [?below], 368
  26778.                  405, 417, 431                   [?equal], 368
  26779.                 Uses Filename_Format, 417        [?file], 368
  26780.                 Uses HeaderHelp, 417             [?line], 368
  26781.                 Uses Leaving, 114, 417           [access], 369
  26782.                 Uses LocateHelp, 417             [accessfile], 369
  26783.                 Uses Logo, 417                   [acs], 369
  26784.                 Uses MaxEdHelp, 418              [acsfile], 369
  26785.                 Uses MsgAreas, 67, 362,          [alist_file], 362
  26786.                  405, 418, 425                   [alist_msg], 362
  26787.                 Uses NewUser1, 418               [ansopt], 366, 367
  26788.                 Uses NewUser2, 418               [ansreq], 366
  26789.                 Uses NoMail, 418                 [apb], 378
  26790.  
  26791.  
  26792.  
  26793.              Index                                                     490
  26794.  
  26795.                 [b1200], 370                     [got, 372
  26796.                 [b2400], 371                     [goto], 356, 357, 367,
  26797.                 [b9600], 371                      374
  26798.                 [bell], 360                      [gray], 358
  26799.                 [bg], 358                        [green], 358
  26800.                 [black], 358                     [hangup], 382
  26801.                 [blink], 358, 359, 360           [hex], 382
  26802.                 [blue], 358                      [hotkeys], 372
  26803.                 [bright], 359                    [ibmchars], 382
  26804.                 [brown], 358                     [ifentered], 365, 372
  26805.                 [bs], 360                        [ifexist], 372
  26806.                 [chat_avail], 379                [iffse], 372
  26807.                 [chat_notavail], 379             [iffsr], 372
  26808.                 [choice], 367                    [ifkey], 369, 370
  26809.                 [city], 362                      [iflang], 83, 372
  26810.                 [ckoff], 381                     [iftask], 373
  26811.                 [ckon], 381                      [iftime], 373
  26812.                 [clear_stacked], 368, 381        [incity], 373
  26813.                 [cleol], 361                     [include], 382
  26814.                 [cleos], 361                     [islocal], 374
  26815.                 [cls], 80, 361                   [isremote], 374
  26816.                 [col80], 371                     [jump], 374
  26817.                 [color], 371                     [key?], 382
  26818.                 [colour], 371                    [key_poke], 382, 383
  26819.                 [comment], 381                   [keyoff], 370
  26820.                 [copy], 381                      [keyon], 370
  26821.                 [cr], 361                        [label], 374
  26822.                 [cyan], 358                      [language], 383
  26823.                 [darkgray], 358                  [lastcall], 363
  26824.                 [date], 362                      [lastuser], 363
  26825.                 [decimal], 381                   [leave_comment], 367, 402
  26826.                 [delete], 382                    [left], 361
  26827.                 [dim], 359                       [length], 363
  26828.                 [dl], 362                        [lf], 361
  26829.                 [dos], 382                       [lightblue], 358
  26830.                 [down], 361                      [lightcyan], 358
  26831.                 [endcolor], 371, 376             [lightgreen], 358
  26832.                 [endcolour], 371                 [lightmagenta], 358
  26833.                 [endrip], 93, 371, 376,          [lightred], 358
  26834.                  377                             [link], 371, 382, 383,
  26835.                 [enter], 367, 382                 384, 466
  26836.                 [exit], 371, 384                 [load], 359
  26837.                 [expert], 371                    [locate], 361
  26838.                 [expiry_date], 362               [log], 383
  26839.                 [expiry_time], 362               [magenta], 358
  26840.                 [fg], 359                        [maxed], 374
  26841.                 [file_carea], 363                [menu], 109, 366, 367,
  26842.                 [file_cname], 363                 368
  26843.                 [file_darea], 363                [menu_cmd], 83, 383
  26844.                 [file_sarea], 363                [menupath], 383
  26845.                 [filenew], 371                   [mex], 167, 383
  26846.                 [first], 363                     [minutes], 363
  26847.                 [fname], 363, 367                [more], 383
  26848.  
  26849.  
  26850.  
  26851.              Index                                                     491
  26852.  
  26853.                 [moreoff], 384                   [ratio], 364
  26854.                 [moreon], 384                    [readln], 365, 366, 367,
  26855.                 [msg_attr], 374                   368, 372, 379
  26856.                 [msg_carea], 363                 [realname], 365
  26857.                 [msg_checkmail], 384,            [red], 358
  26858.                  418, 447                        [regular], 377
  26859.                 [msg_cmsg], 363                  [remain], 365
  26860.                 [msg_cname], 364                 [repeat], 384
  26861.                 [msg_conf], 375                  [repeatseq], 384
  26862.                 [msg_darea], 364                 [response], 365
  26863.                 [msg_echo], 375                  [right], 361
  26864.                 [msg_fileattach], 87, 375        [rip], 93, 377
  26865.                 [msg_hmsg], 364                  [ripdisplay], 94, 379,
  26866.                 [msg_local], 375                  411
  26867.                 [msg_matrix], 376                [riphasfile], 94, 377
  26868.                 [msg_next], 376                  [rippath], 94, 379, 380,
  26869.                 [msg_nomsgs], 376                 412
  26870.                 [msg_nonew], 376                 [ripsend], 93, 94, 322,
  26871.                 [msg_noread], 376                 378, 379, 380, 411
  26872.                 [msg_nummsg], 364                [save], 359, 360
  26873.                 [msg_prior], 376                 [setpriv], 369
  26874.                 [msg_sarea], 364                 [sopen], 368
  26875.                 [netbalance], 364                [steady], 360
  26876.                 [netcredit], 364                 [store], 366, 367, 368
  26877.                 [netdebit], 364                  [string], 385
  26878.                 [netdl], 364                     [subdir], 385
  26879.                 [newfiles], 383, 384, 444        [sys_name], 365
  26880.                 [no_keypress], 376, 377          [syscall], 365
  26881.                 [nocolor], 376                   [sysop_name], 365, 391
  26882.                 [nocolour], 376                  [sysopbell], 362
  26883.                 [node_num], 364                  [tab], 361
  26884.                 [norip], 376                     [tag_read], 385
  26885.                 [nostacked], 376, 377            [tag_write], 385
  26886.                 [notkey], 370                    [tagged], 378
  26887.                 [notontoday], 377                [textsize], 380
  26888.                 [novice], 377                    [time], 365
  26889.                 [ofs], 377                       [timeoff], 365
  26890.                 [on], 360                        [top], 378
  26891.                 [onexit], 384                    [tune], 385
  26892.                 [open], 112, 366, 367,           [ul], 365
  26893.                  368                             [unsigned], 385
  26894.                 [pause], 384, 464                [up], 362
  26895.                 [permanent], 377                 [user], 365
  26896.                 [phone], 364                     [usercall], 355, 366
  26897.                 [post], 112, 366, 367,           [white], 358
  26898.                  368                             [write], 112, 366, 368,
  26899.                 [priv_abbrev], 369                466
  26900.                 [priv_desc], 369                 [xclude], 368
  26901.                 [priv_down], 369                 [xtern_dos], 105, 113,
  26902.                 [priv_level], 369                 385
  26903.                 [priv_up], 369                   [xtern_erlvl], 106, 385
  26904.                 [quit], 80, 371, 384             [xtern_run], 106, 113,
  26905.                 [quote], 357, 384, 418            385
  26906.  
  26907.  
  26908.  
  26909.              Index                                                     492
  26910.  
  26911.                 [yellow], 357, 358               Edit_Insert, 20, 443
  26912.              menu options                        Edit_List, 19, 443
  26913.                 linked, 81, 437, 442, 449        Edit_Quote, 20, 443
  26914.              MenuFile, 435                       Edit_Save, 19, 443
  26915.              menus                               Edit_Subj, 18, 20, 443
  26916.                 dynamic, 67                      Edit_To, 18, 20, 443
  26917.              menus control file. See             End Menu, 434
  26918.               menus.ctl                          File_Area, 21, 407, 433,
  26919.              menus.ctl, 40                        443
  26920.                 Chat_Answer, 29                  File_Contents, 24, 416,
  26921.                 Chat_CB, 28, 439                  443
  26922.                 Chat_Page, 28, 439               File_Download, 22, 418,
  26923.                 Chat_Pvt, 439                     444
  26924.                 Chat_Toggle, 29, 439             File_Hurl, 24, 67, 444
  26925.                 Chg_Alias, 25, 439               File_Kill, 24, 444
  26926.                 Chg_Archiver, 27, 30, 439        File_Locate, 21, 72, 407,
  26927.                 Chg_City, 25, 439                 417, 444
  26928.                 Chg_Clear, 440                   File_NewFiles, 75, 444
  26929.                 Chg_Editor, 440                  File_Override, 24, 444
  26930.                 Chg_FSR, 27, 440                 File_Raw, 24, 444, 483
  26931.                 Chg_Help, 25, 440                File_Tag, 23, 444, 483
  26932.                 Chg_Hotkeys, 27, 440             File_Titles, 21, 444
  26933.                 Chg_IBM, 26, 440                 File_Type, 444
  26934.                 Chg_Language, 27, 82,            File_Upload, 418, 445
  26935.                  133, 383, 440                   File_View, 22
  26936.                 Chg_Length, 26, 440              Goodbye, 8, 15, 416, 445
  26937.                 Chg_More, 26, 440                HeaderFile, 434
  26938.                 Chg_Nulls, 25, 441               Key_Poke, 439, 445
  26939.                 Chg_Password, 25, 441            Leave_Comment, 391, 446
  26940.                 Chg_Phone, 25, 441               Link_Menu, 311, 442, 446,
  26941.                 Chg_Protocol, 27, 29, 441         449
  26942.                 Chg_Realname, 441                Local, 436
  26943.                 Chg_RIP, 92, 441                 Matrix, 436
  26944.                 Chg_Tabs, 26, 441                Menu, 434, 435
  26945.                 Chg_Userlist, 9, 27, 441         MenuColor, 435
  26946.                 Chg_Video, 26, 441               MenuFile, 80, 434, 435
  26947.                 Chg_Width, 26, 441               MenuLength, 435
  26948.                 Clear_Stacked, 442               MEX, 167, 311
  26949.                 Conf, 436                        Msg_Area, 11, 408, 429,
  26950.                 Ctl, 436                          446
  26951.                 Display_File, 83, 111,           Msg_Browse, 14, 15, 408,
  26952.                  167, 311, 442                    446, 448, 481
  26953.                 Display_Menu, 81, 83,            Msg_Change, 13, 446
  26954.                  121, 437, 442                   Msg_Checkmail, 447
  26955.                 Echo, 436                        Msg_Current, 447
  26956.                 Edit_Abort, 19, 442              Msg_Download_Attach, 87,
  26957.                 Edit_Continue, 18, 20,            447
  26958.                  442                             Msg_Edit_User, 447
  26959.                 Edit_Delete, 20, 442             Msg_Enter, 11, 12, 447
  26960.                 Edit_Edit, 19, 419, 442          Msg_Forward, 16, 447
  26961.                 Edit_From, 18, 20, 443           Msg_Hurl, 17, 447
  26962.                 Edit_Handling, 19, 20,           Msg_Kill, 15, 410, 447
  26963.                  443
  26964.  
  26965.  
  26966.  
  26967.              Index                                                     493
  26968.  
  26969.                 Msg_Kludges, 97, 102,             375, 389, 396, 397, 398,
  26970.                  397, 398, 447                    426, 428, 429, 446
  26971.                 Msg_Reply, 13, 410, 427,         hierarchical, 68
  26972.                  447                             Local, 9, 12, 140, 396,
  26973.                 Msg_Reply_Area, 448               428, 429, 436
  26974.                 Msg_Restrict, 448                NetMail, 9, 10, 12, 13,
  26975.                 Msg_Tag, 15, 29, 448, 483         16, 17, 19, 20, 41, 45,
  26976.                 Msg_Track, 96, 99                 48, 49, 50, 87, 88, 91,
  26977.                 Msg_Unreceive, 448                92, 132, 140, 257, 376,
  26978.                 Msg_Upload, 16, 90, 410,          390, 396, 397, 398, 429,
  26979.                  448, 463                         446, 453, 482
  26980.                 Msg_Upload_QWK, 29, 448          packing, 51
  26981.                 Msg_Xport, 17, 448               read-only, 10
  26982.                 NoCLS, 437                       renumbering, 51
  26983.                 NoDsp, 81, 437                message tracking system. See
  26984.                 NoRIP, 94, 437                  MTS
  26985.                 OptionWidth, 436              messages
  26986.                 Press_Enter, 80, 449             anonymous, 11
  26987.                 Read_Current, 14                 audit trail, 97, 102
  26988.                 Read_DiskFile, 449               downloading, 89
  26989.                 Read_Individual, 449             editing, 19
  26990.                 Read_Next, 11, 449               forwarding, 16
  26991.                 Read_Nonstop, 13, 449            printing, 17, 448
  26992.                 Read_Original, 13, 449           priority, 97
  26993.                 Read_Previous, 12, 449           private, 10
  26994.                 Read_Reply, 14, 449              public, 10
  26995.                 ReRead, 114, 437                 quoting, 18, 20
  26996.                 Return, 446, 449                 renumbering, 136
  26997.                 RIP, 94, 437                     tracking, 95
  26998.                 Same_Direction, 449              uploading, 90
  26999.                 Title, 436                    MEX, 1, 112, 161, 169, 434,
  27000.                 Track Base, 98                  461
  27001.                 Track Exclude, 98                arguments
  27002.                 Track Modify, 98                  pass-by-reference, 202,
  27003.                 Track View, 98                     232
  27004.                 User_Editor, 28, 450             arrays, 206, 231
  27005.                 Userlist, 9, 450                  accessing, 207
  27006.                 UsrLocal, 437                     as function parameters,
  27007.                 UsrRemote, 437                     210
  27008.                 Version, 80, 450                  declaring, 206
  27009.                 Who_Is_On, 9, 379, 399,          blocks, 227
  27010.                  400, 450                        casts, 223
  27011.                 Xtern_DOS, 105, 437, 450          printing using, 223
  27012.                 Xtern_Erlvl, 106, 107,           comments, 163, 227
  27013.                  115, 311, 450, 469              compiler, 165
  27014.                 Xtern_Run, 106, 437, 450         directive
  27015.                 Yell, 8, 450, 459                 #include, 179, 200, 227,
  27016.              message area control file.            242
  27017.               See msgarea.ctl                    directives, 179
  27018.              message areas, 39, 64               escape sequences, 164,
  27019.                 EchoMail, 9, 10, 45, 48,          176
  27020.                  49, 50, 51, 66, 96, 102,        function, 163
  27021.                  132, 139, 140, 141, 253,        functions, 227
  27022.  
  27023.  
  27024.  
  27025.              Index                                                     494
  27026.  
  27027.                  arguments, 200                  create_static_string,
  27028.                  arguments for, 163               270, 282, 283, 284, 285,
  27029.                  calling, 163, 194                296, 325, 326
  27030.                  definitions, 198                dcd_check, 266, 275, 283
  27031.                  prototypes, 198, 229            destroy_static_data, 270,
  27032.                  return values, 203, 229          284
  27033.                 language files and, 461          destroy_static_string,
  27034.                 statement                         270, 284
  27035.                  compound, 230                   display_file, 264, 286
  27036.                  do while, 190                   Display_Menu, 311
  27037.                  for, 191, 231                   do_more, 263, 286, 287,
  27038.                  goto, 192                        288
  27039.                  if, 187                         file_area, 267, 288
  27040.                  return, 165, 195                fileareafindclose, 267,
  27041.                  while, 189                       288, 289, 290
  27042.                 strings, 164, 177, 229           fileareafindfirst, 267,
  27043.                  assigning, 177                   289, 290, 291
  27044.                  indexing, 177, 178              fileareafindnext, 267,
  27045.                 structures, 214, 232              290, 291
  27046.                  as arguments, 221               fileareafindprev, 267,
  27047.                  declaring variables as,          290
  27048.                   216, 232                       fileareaselect, 237, 267,
  27049.                  defining types, 215              291
  27050.                 types, 228                       filecopy, 264, 291
  27051.                 variables, 174                   filedate, 261, 264, 292
  27052.                  declaring, 228                  fileexists, 264, 292, 293
  27053.              MEX directives                      filefindclose, 264, 293,
  27054.                 #include, 162                     294
  27055.              MEX functions                       filefindfirst, 264, 293,
  27056.                 ansi_detect, 271, 272             294
  27057.                 call_close, 268, 272             filefindnext, 265, 294
  27058.                 call_numrecs, 268, 273,          filesize, 261, 264, 293,
  27059.                  274                              294, 295, 321, 322
  27060.                 call_open, 268, 272, 273,        get_static_data, 270,
  27061.                  274, 388                         295, 325
  27062.                 call_read, 269, 273, 274         get_static_string, 270,
  27063.                 carrier, 266, 275, 284            296, 297, 325
  27064.                 chat_querystatus, 260,           getch, 239, 263, 297,
  27065.                  270, 275                         306, 307
  27066.                 chatstart, 270, 276              hstr, 270, 297, 298, 309
  27067.                 class_abbrev, 269, 276           input_ch, 238, 239, 251,
  27068.                 class_info, 269, 277, 279         252, 263, 297, 298, 301,
  27069.                 class_loginfile, 269, 279         304, 306
  27070.                 class_name, 269, 280             input_list, 238, 239,
  27071.                 class_to_priv, 269, 280           251, 252, 263, 299, 300,
  27072.                 close, 264, 281                   301, 306
  27073.                 compressor_num_to_name,          input_str, 238, 251, 252,
  27074.                  268, 281                         263, 302, 306, 348
  27075.                 create_static_data, 270,         iskeyboard, 263, 304
  27076.                  281, 282, 283, 284, 295,        issnoop, 263, 305
  27077.                  296, 325                        itostr, 266, 305, 309,
  27078.                                                   343, 344
  27079.                                                  kbhit, 263, 306, 307
  27080.  
  27081.  
  27082.  
  27083.              Index                                                     495
  27084.  
  27085.                 keyboard, 263, 306               sleep, 266, 327
  27086.                 language_num_to_name,            snoop, 263, 328
  27087.                  268, 307                        stamp_string, 265, 328
  27088.                 language_num_to_string,          stamp_to_long, 236, 265,
  27089.                  307                              329
  27090.                 localkey, 263, 307               strfind, 265, 329
  27091.                 log, 269, 307                    stridx, 265, 330, 333
  27092.                 long_to_stamp, 265, 308          strlen, 230, 265, 331,
  27093.                 lstr, 270, 308, 309               349
  27094.                 ltostr, 266, 309, 343            strlower, 265, 331
  27095.                 mdm_command, 266, 309,           strpad, 265, 331, 332
  27096.                  310                             strpadleft, 265, 332
  27097.                 mdm_flow, 267, 310               strridx, 265, 330, 332,
  27098.                 menu_cmd, 264, 310                333
  27099.                 msg_area, 267, 311               strtoi, 266, 333
  27100.                 msgareafindclose, 267,           strtok, 265, 334
  27101.                  311                             strtol, 266, 334, 335
  27102.                 msgareafindfirst, 267,           strtrim, 265, 336
  27103.                  311, 312, 313                   strupper, 265, 336
  27104.                 msgareafindnext, 267, 313        substr, 265, 336, 337
  27105.                 msgareafindprev, 267, 313        tag_dequeue_file, 268,
  27106.                 msgareaselect, 237, 267,          337
  27107.                  314                             tag_get_name, 268, 338
  27108.                 open, 264, 281, 314, 318,        tag_queue_file, 239, 268,
  27109.                  319, 323, 339, 348               338, 339
  27110.                 print, 163, 185, 263, 315        tag_queue_size, 268, 338,
  27111.                 privok, 269, 317                  339
  27112.                 prm_string, 269, 318             tell, 264
  27113.                 protocol_num_to_name,            term_length, 257, 263,
  27114.                  268, 318                         340
  27115.                 read, 264, 318, 319, 339         term_width, 257, 263, 340
  27116.                 readln, 264, 319, 339,           time, 265, 308, 340
  27117.                  366, 372                        time_check, 265, 341
  27118.                 remove, 264, 320                 timeadjust, 265, 341
  27119.                 rename, 264, 320                 timeadjustsoft, 265, 341,
  27120.                 reset_more, 263, 287, 321         342
  27121.                 rip_detect, 271, 321             timeleft, 266
  27122.                 rip_hasfile, 94, 271,            timeon, 266
  27123.                  321, 322                        timestamp, 266
  27124.                 rip_send, 94, 271, 322           uitostr, 266, 305, 343
  27125.                 screen_length, 257, 263,         ultostr, 266, 309, 343
  27126.                  323                             usercreate, 268
  27127.                 screen_width, 257, 263,          userfilesize, 268, 344
  27128.                  323                             userfindclose, 268, 344
  27129.                 seek, 264, 323                   userfindnext, 268, 346
  27130.                 set_output, 263, 324             userfindopen, 268, 345,
  27131.                 set_static_data, 270,             346
  27132.                  295, 296, 325                   userfindprev, 268, 345,
  27133.                 set_static_string, 270,           346
  27134.                  296, 325                        userfindseek, 268, 346
  27135.                 set_textsize, 263, 326,          userremove, 268, 347
  27136.                  340                             userupdate, 268, 347
  27137.                 shell, 105, 106, 264, 326
  27138.  
  27139.  
  27140.  
  27141.              Index                                                     496
  27142.  
  27143.                 vidsync, 252, 263, 347,          Override, 426
  27144.                  348                             Owner, 98, 100, 102, 427,
  27145.                 write, 264, 339, 348              428
  27146.                 writeln, 264, 339, 348,          Path, 65, 427
  27147.                  349                             Renum Days, 137, 427
  27148.                 xfertime, 266, 349               Renum Max, 137, 428
  27149.              MEX globals                         Style, 65, 428
  27150.                 farea, 254                       Style *.MSG, 66, 428
  27151.                 id, 252                          Style Alias, 399, 428
  27152.                 input, 251                       Style Anon, 428
  27153.                 marea, 253                       Style Attach, 87, 88,
  27154.                 msg, 254                          390, 428
  27155.                 sys, 259                         Style Audit, 98, 102,
  27156.                 usr, 255                          427, 428
  27157.              MEX structs                         Style Conf, 428, 436
  27158.                 _callinfo, 261                   Style Echo, 429, 436, 463
  27159.                 _cstat, 260                      Style HiBit, 429
  27160.                 _date, 259                       Style Hidden, 408, 429
  27161.                 _farea, 254                      Style Loc, 429
  27162.                 _ffind, 261                      Style Local, 429, 436
  27163.                 _instancedata, 252               Style Net, 87, 429, 436
  27164.                 _marea, 253                      Style NoMailCheck, 429
  27165.                 _msg, 254                        Style NoNameKludge, 11,
  27166.                 _stamp, 260                       428, 429
  27167.                 _sys, 259                        Style Pub, 66, 429
  27168.                 _time, 260                       Style Pvt, 65, 429
  27169.                 _usr, 255                        Style ReadOnly, 429, 453
  27170.              modem, 1, 3, 5, 33, 34, 35,         Style RealName, 399, 429
  27171.               36, 37, 42, 43, 85, 86,            Style Squish, 66, 428,
  27172.               112, 266, 275, 297, 309,            429
  27173.               310, 392, 393, 394, 395,           Style Tag, 429
  27174.               423, 464                           Tag, 66, 140, 396, 406
  27175.                 V.32, 37                      MSR, 394
  27176.                 V.34, 35, 37                  MTS, 95, 96, 97, 98, 99,
  27177.                 V.FC, 35, 37                    101, 104, 413, 427, 428
  27178.              modem cable. See cable              QWK packets and, 101
  27179.              modem status register. See          reports, 97, 100
  27180.               MSR                             multinode, 117
  27181.              more prompt, 26
  27182.              MR, 51, 136, 137, 427, 428            N
  27183.              msgarea.ctl, 40                  NetMail
  27184.                 ACS, 65, 66, 424                 credit, 10, 41, 453
  27185.                 AttachPath, 87, 401, 424         QWK packets and, 91
  27186.                 Barricade, 77, 424, 465       NoAccess, 60
  27187.                 Desc, 65, 66, 406, 424        nodelist, 397, 398
  27188.                 Description, 424              Novell, 38
  27189.                 End MsgArea, 64, 424, 425
  27190.                 FileDivisionEnd, 69                O
  27191.                 MenuName, 425, 463            off-line reader, 29
  27192.                 MsgArea, 64, 69, 424, 425     off-line reader control
  27193.                 MsgDivisionBegin, 68, 69        file. See reader.ctl
  27194.                 MsgDivisionEnd, 69, 425       Opus, 35, 127, 128, 454,
  27195.                 Origin, 426                     455, 456, 457, 458
  27196.  
  27197.  
  27198.  
  27199.              Index                                                     497
  27200.  
  27201.              OpusComm, 2, 35, 36                   Q
  27202.              ORACLE, 64, 127, 137, 138        questionnaire, 355, 366,
  27203.              origin line, 426, 463              367, 368
  27204.              OS/2, 1, 3, 26, 28, 31, 32,      QuickBBS, 112, 127, 128
  27205.               34, 35, 38, 39, 42, 43,         quote, 13, 18, 20, 92, 96,
  27206.               44, 45, 49, 50, 54, 71,           101, 102, 176, 177, 244,
  27207.               86, 105, 115, 117, 118,           384, 409
  27208.               119, 120, 121, 122, 123,        QWK, 15, 27, 81, 82, 88, 89,
  27209.               134, 138, 142, 145, 162,          90, 91, 92, 96, 101, 421,
  27210.               242, 253, 327, 328, 390,          439, 446, 448, 463, 481,
  27211.               392, 393, 394, 414, 469,          482
  27212.               475, 476, 478
  27213.                                                    R
  27214.                   P                           ratio
  27215.              packer, 29, 49, 50, 81, 82,         download, 55
  27216.               88, 101, 446. See also          RBBS, 112
  27217.               off-line reader                 reader control file. See
  27218.              PAK, 443                           reader.ctl
  27219.              Path NetInfo, 398                reader.ctl
  27220.              phone number, 6, 41, 110,           Archivers, 421
  27221.               114, 155, 159, 220, 256,           Max Messages, 82, 421
  27222.               364, 400, 415, 421, 473            Packet Name, 82, 421
  27223.              PID, 428                            Phone Number, 82, 421
  27224.              printing                            Work Directory, 421
  27225.                 messages, 448                 real name, 11, 110, 365,
  27226.              printing messages, 17              399, 428, 429
  27227.              privilege level, 56              result codes, 33, 86
  27228.              protocol, 27                     reward, 454
  27229.                 Opus-compatible, 455, 458     REXX, 145, 146
  27230.              protocol control file. See       REXX API
  27231.               protocol.ctl                       MaxLoadFuncs, 146
  27232.              protocol.ctl, 458                   MaxUnloadFuncs, 146
  27233.                 ControlFile, 455                 UserFileClose, 147
  27234.                 DescriptWord, 455                UserFileCreateRecord, 147
  27235.                 DownloadCmd, 455                 UserFileFind, 148
  27236.                 DownloadKeyword, 456             UserFileFindClose, 148
  27237.                 DownloadString, 455, 456,        UserFileFindNext, 149,
  27238.                  457                              150
  27239.                 End Protocol, 456                UserFileFindOpen, 149,
  27240.                 FilenameWord, 456                 150
  27241.                 LogFile, 457                     UserFileFindPrior, 150
  27242.                 Protocol, 457                    UserFileGetNewLastread,
  27243.                 Type Batch, 457                   147, 150, 155
  27244.                 Type Bi, 457                     UserFileInitRecord, 147,
  27245.                 Type Opus, 455, 457               151
  27246.                 UploadCmd, 458                   UserFileOpen, 147, 150,
  27247.                 UploadKeyword, 455, 456,          151, 152
  27248.                  457, 458                        UserFileSize, 152
  27249.                 UploadString, 455, 457,          UserFileUpdate, 152
  27250.                  458                          RIPscrip, 6, 12, 17, 26, 27,
  27251.                                                 41, 92, 93, 94, 135, 156,
  27252.                                                 256, 263, 270, 271, 321,
  27253.                                                 322, 326, 371, 376, 377,
  27254.  
  27255.  
  27256.  
  27257.              Index                                                     498
  27258.  
  27259.               378, 379, 380, 381, 402,          383, 385, 404, 407, 442,
  27260.               411, 417, 434, 435, 437,          445
  27261.               441                             TSR, 36
  27262.              runbbs.bat, 49, 51, 54, 107,     TTY, 26, 110, 138, 153, 256,
  27263.               120, 132                          358, 411, 441, 483
  27264.              runbbs.cmd. See runbbs.bat
  27265.              runfb.bat, 131                        U
  27266.                                               Upload, 16, 23, 29, 67, 90,
  27267.                   S                             410, 414, 415, 433, 445,
  27268.              Save Directories, 73, 412          448
  27269.              SCANBLD, 49, 138, 139, 140,         reward, 39
  27270.               141                             user editor, 15, 28, 41, 58,
  27271.              scanner, 50, 475, 477              94, 447, 450, 469, 473
  27272.              screen writes, 252               user file
  27273.              SEAlink, 22, 158                    creating, 41
  27274.              security, 41, 55, 88, 390           encryption, 41
  27275.              SEEN-BY, 426                     Uses Leaving, 417
  27276.              serial cards
  27277.                 intelligent, 35, 117               V
  27278.              Session Monitor. See SM          Version, 9, 398
  27279.              SHARE.EXE, 389
  27280.              shell, 28                             W
  27281.              SILT, 40, 73, 100, 141, 142,     WFC, 49, 53, 54, 85
  27282.               166, 387, 388, 425, 430,        WildCat!, 112
  27283.               431, 433, 453                   Windows, 389
  27284.              SILT directive                      Windows 95, 39, 120
  27285.                 Include, 387                     Windows for Workgroups,
  27286.                 Version14, 387                    39
  27287.                 Version17, 387                WWIV, 112, 113
  27288.              SIO, 35, 115
  27289.              SM, 142                               X
  27290.              source file                      X00, 2, 36, 37
  27291.                 MEX, 162                      Xmodem, 22, 23, 158
  27292.              spawnbbs.bat, 44                 XMS
  27293.              SQPACK, 51                          swapping to, 391
  27294.              Squish, 45, 49, 65, 66, 396,
  27295.               420, 421, 427, 428                   Z
  27296.              squish.cfg, 427, 428             ZIP, 72, 443
  27297.              startup.cmd, 120                 Zmodem, 2, 22, 158, 458, 470
  27298.              subscription, 94, 362
  27299.              swapping, 106
  27300.              system control file. See
  27301.               max.ctl
  27302.  
  27303.                   T
  27304.              tab characters, 26
  27305.              tear line, 428, 429
  27306.              TheDraw, 127
  27307.              TRACKEXP, 103, 104
  27308.              TRACKIMP, 104
  27309.              translation characters, 8,
  27310.               15, 22, 109, 111, 112,
  27311.               309, 366, 367, 368, 382,
  27312.