UCLA/Mail Reference (OFCREF) V1.500 University of California Office of Academic Computing 5628 Math Sciences Addition Los Angeles, California 90024 Michael Stein OAC Systems csysmas@mvs.oac.ucla.edu Copyright Regents University of California, 1984, 1985, 1986, 1988, 1991. DISCLAIMER __________ The University of California requires the following disclaimer concerning all distributed programs: Although this program has been tested by its contributor, no warranty, expressed or implied, is made by the contributor or the University of California, as to the accuracy and functioning of the program and related program material, nor shall the fact of the distribution constitute any such warranty, and no responsibility is assumed by the contributor or the University of California, in connection therewith. 06/21/91 17:40 UCLA/Mail reference (OFCREF) Page ii CONTENTS ________ Introduction . . . . . . . . . . . . . . . . . . . . . . 1 Mail design goals . . . . . . . . . . . . . . . . . . 1 Mail current status . . . . . . . . . . . . . . . . . 2 Overview . . . . . . . . . . . . . . . . . . . . . . . . 2 Local mail . . . . . . . . . . . . . . . . . . . . . . 3 NJE connection . . . . . . . . . . . . . . . . . . . . 3 File Support . . . . . . . . . . . . . . . . . . . . . 4 Bitnet . . . . . . . . . . . . . . . . . . . . . . . . 5 Internet (TCP/IP) . . . . . . . . . . . . . . . . . . 5 Internet mail addressing and domain name system . . . 6 UCLA/Mail domain support . . . . . . . . . . . . . . . 8 Installation . . . . . . . . . . . . . . . . . . . . . 10 Prerequisites . . . . . . . . . . . . . . . . . . . 10 Mail Installation options . . . . . . . . . . . . . 11 Installation . . . . . . . . . . . . . . . . . . . . 12 Distribution tape contents . . . . . . . . . . . 12 Installation tasks . . . . . . . . . . . . . . . 14 DEMO installation (fast path for DEMO only) . . . 14 EXEC, initialization, and definition statements . . . . 21 EXEC parameters . . . . . . . . . . . . . . . . . . 22 Initialization statements: (usually in OFCINIT) . . 22 IPC statement . . . . . . . . . . . . . . . . . . 22 OPT statement . . . . . . . . . . . . . . . . . . 22 DEBUG statement . . . . . . . . . . . . . . . . . 25 DUMP statement . . . . . . . . . . . . . . . . . 26 PURGE statement . . . . . . . . . . . . . . . . . 26 DESTLIST statement . . . . . . . . . . . . . . . 26 SYM statement . . . . . . . . . . . . . . . . . . 27 NJE statement . . . . . . . . . . . . . . . . . . 28 VTAM statement . . . . . . . . . . . . . . . . . 31 VSAM statement . . . . . . . . . . . . . . . . . 32 DOMAINS statement . . . . . . . . . . . . . . . . 32 Domain definition statements . . . . . . . . . . . . 33 ALIAS statement . . . . . . . . . . . . . . . . . 33 EQUIV statement . . . . . . . . . . . . . . . . . 33 ROUTE statement . . . . . . . . . . . . . . . . . 34 NET statement . . . . . . . . . . . . . . . . . . 36 | Networks . . . . . . . . . . . . . . . . . . . . . . . 36 | BITNET, EARN, Netnorth (etc...) . . . . . . . . . . 38 | OFCBIT table generation utility . . . . . . . . . 39 | Internet (TCP/IP networks) . . . . . . . . . . . . . 39 | IBM's TCP/IP (& SMTP) . . . . . . . . . . . . . . 39 UCLA/ACP . . . . . . . . . . . . . . . . . . . . 45 | IBMIN (& IBMLink) . . . . . . . . . . . . . . . . . 45 Mail Gateway . . . . . . . . . . . . . . . . . . . . 45 Operations . . . . . . . . . . . . . . . . . . . . . . 46 Operator commands (post office) . . . . . . . . . . 46 VSAM File Maintenance and Recovery . . . . . . . . . 47 Dumps . . . . . . . . . . . . . . . . . . . . . . 47 Message purging . . . . . . . . . . . . . . . . . 48 VSAM reload (& batch processing) . . . . . . . . 48 UCLA/Mail reference (OFCREF) Page iii Internals . . . . . . . . . . . . . . . . . . . . . . . 49 Post Office module guide . . . . . . . . . . . . . . 49 Mail VSAM cluster structure . . . . . . . . . . . . 51 OFC IPC interface . . . . . . . . . . . . . . . . . 52 Notification . . . . . . . . . . . . . . . . . . . . 53 VSAM gas (non-DFP only) . . . . . . . . . . . . . . 53 Mail formats (RFC822 and Bitnet) . . . . . . . . . . 54 Postman (and mail loops) . . . . . . . . . . . . . . 55 User Exits (OFCEXIT - OFCX....) . . . . . . . . . . 56 OFCXINIT - initialization/termination exit . . . 56 OFCXBOX - validity check mail box name . . . . . 56 OFCXNOTE - local notify exit . . . . . . . . . . 56 OFCXUSR - map jobname & userid to true userid . 56 OFCXACC - message access control exit . . . . . 57 OFCXROUT - message routing exit . . . . . . . . . 57 OFCXPROT - message protocol exit . . . . . . . . 57 OFCXVIEW - address view generator exit . . . . . 57 Control Blocks (& Logic!) . . . . . . . . . . . . . 57 Miscellaneous . . . . . . . . . . . . . . . . . . . . . 60 Additional Information Sources . . . . . . . . . . . 60 UCLA/Mail Interested party list (LISTSERV list) . 60 UCLA/Mail developers . . . . . . . . . . . . . . 60 Others . . . . . . . . . . . . . . . . . . . . . 61 CICS user agent (none) . . . . . . . . . . . . . . . 61 X-UR-File definition . . . . . . . . . . . . . . . . 61 INDEX . . . . . . . . . . . . . . . . . . . . . . . 64 UCLA/Mail reference (OFCREF) Page 1 INTRODUCTION UCLA had a local message service for many years under MVT, first on the 360/91KK and later on the 3033UP. The message service did not survive the conversion to MVS. Several years after the conversion (and the dust had settled) the message system was still missed. There was also no easy way to communicate with the NJE connected VM/CMS 4341. This problem was intensified when UCLA was connected to Bitnet. Most of our users were on the MVS system and only the VM users could easily use Bitnet. It became obvious that this situation was not going to disappear and UCLA/Mail was born. This is the V1.500 UCLA/Mail distribution. This is an "AS IS" distribution and will need to be tailored to your installations needs. Mail design goals _________________ The goals for the UCLA mail system are: * The mail system must evolve. A working mail system was required quickly even if this meant that the first usable version would not have all the fancy features possible. Starting out simply also allows for feedback to affect the design. * Reliability / Availability The mail system must be reliable. It is viewed by our computer center users as a utility like the telephone and must be available whenever the computer(s) are available. The post office must be capable of continuous operation without forced restarts. A minimum goal is 1 week of continuous operation. * Recoverability The mail system file must be easily recovered and it must be possible to process it with standard utilities. * Failure modes The mail system must not impact other parts of the system when it fails. Failures must be localized and easily fixed. * Interface with other mail systems The mail system must interface with other mail systems, in particular VM/CMS including Bitnet, and hopefully ARPA. | An interface with the Internet is now seen as much more | desirable. Design decisions included: * There will not be a mail file for each user UCLA/Mail reference (OFCREF) Page 2 The large track size of the 3380, our primary DASD storage type, and the number of userids (> 10k) suggested that our disks would be flooded with mostly empty 1 track datasets if mail was delivered to actual files for each user. * Mail processors will match their environments The TSO mail command and the WYLBUR interfaces will have separate command structures and help tailored to fit in with their separate environments. * Mail file recovery must be simple Mail file recovery was a big concern, but this was tempered by the overhead required for absolute recovery capability. The I/O overhead to duplex the file or to keep a complete audit trail was considered unacceptable. Some loss of recent mail was considered acceptable when a file is destroyed (disk crash for example), but losing all records was not. A message re-appearing if the file is restored was considered minor. | I'm rethinking this -- a complete audit trail for file | recovery is on my list. I have too many "dependent" UCLA | administrators now. There is no time estimate for this. * The post office is not a file cabinet, and messages will be periodically purged. (Mail travels through and is delivered, it is not for long term storage). * Sharing the mail file is not supported. The post office VSAM cluster must not be shared. There are many design choices which assume that the file is not shared and that all file updaters have unique TOD clock values. * The format of the message headers will be guided by the Internet's RFC822. Mail current status ___________________ The basic local mail system of UCLA/Mail has been in use at UCLA since 1984. Many other sites are also running UCLA/Mail, both on and off of Bitnet. At UCLA general access to local, Bitnet, and the Internet are operational from mail user agents on TSO and WYLBUR. UCLA has three pathways to the Internet. IBM's TCP/IP SMTP, the (very) old UCLA/ACP TCP/IP SMTP interface, and the standard Bitnet INTERBIT node gateways. The UCLA/ACP is a TCP/IP for MVS and is NOT included with UCLA/Mail. It is being phased out in favor of IBM's TCP/IP product. IBM's TCP/IP is already the primary TCP/IP product at UCLA. OVERVIEW UCLA/Mail reference (OFCREF) Page 3 Local mail __________ UCLA/Mail is basically divided into two logical parts, mail user agents (UAs) and the mail transfer agent (MTA or post office) which run in different address spaces and communicate via UCLA/IPC connections. The mail user agents are the actual commands that interfaces with the mail user. Examples are the TSO mail CP or the mail processing code in WYLBUR. Some special purpose mail user agents also exist. An example would be the TSO LOGON mail check code which just states "mail waiting" if any unseen mail exists. A mail user agent which sends mail needs an editor to allow the mail to be built. Usually the user environment already includes an existing editor which the user agent can use. Thus the WYLBUR user agent uses the WYLBUR editor and the TSO UA can send from datasets which can be edited with any of the standard TSO editors (including ISPF). The mail transfer agent (or post office) provides the user agents with the required mail storage and delivery services. It also contains some common user agent function to avoid duplicating this function in each user agent. Some of the services are send message, read message, read message index, check mailbox for unseen messages, and generate reply header. (See the macro OFCREQ and the module OFCMAIL for more detail). The mail transfer agent (post office) owns the VSAM cluster which holds the all the mail. The post office can serve multiple user agents at the same time. It is internally multi-threaded, but does synchronous VSAM file I/O (so far). NJE connection ______________ The post office can communicate with an NJE network to send and receive mail. It is a real NJE node on the NJE network but it is limited to sending/receiving SYSOUT files. The connection to the NJE network is an APPL to APPL VTAM SNA/NJE session with JES2. This session is usually to the JES2 on the same MVS system. As a real NJE node the post office has full access to NJE headers, receiving them on inbound mail and building them on outbound mail. This allows it to simulate many of the attributes of a VM node. Mail sent out on the network looks to VM nodes as if it were sent from a VM node as the post office builds VM dataset header NJE sections. The NJE reception code can also convert some special data formats to normal record format. Thus messages in NETDATA or VM DISK DUMP format are directly useable. UCLA/Mail reference (OFCREF) Page 4 File Support ____________ Post office file support consists of allocating a real MVS sequential dataset and copying the SYSOUT into it. This support is optional, see the NJE initialization options for information on configuring this (on or off). This can be used to handle large or strange SYSOUTs which either would be destroyed by being "forced" into the post office file, can't fit in the post office mail file, or you would rather not have placed there. After the copy, a message is sent to the user informing him that the file has arrived. Unlike mail processing, special format SYSOUTs (NETDATA, VM DISK DUMP) are not converted, but are copied unchanged into the real dataset. The user can convert this dataset to the format he wants at his convenience (and with his options). NETDATA format files can be converted using the standard IBM TSO/E Receive command with the Indataset option. This mode of file processing doesn't leave files in JES2 spool. The datasets created by the post office for the users are deleted by the post office when the above mentioned "informational" message is deleted. This message could be deleted by the user (hopefully AFTER he uses the file) or by the normal message purge processing. The post office will optionally erase the contents of the dataset before the delete. When an NJE sysout arrives at the post office the post office decides if it should be handled as mail or as a file. The post office uses information in the NJE headers and the actual contents and size of the SYSOUT to make this decision. The only problem is: What's a file? One approach is to decide that files are things which aren't mail. Unfortunately different people and sites differ on their definitions of mail too. A minimum choice is that anything which can't fit in the post office should be tried as a file rather than just rejected. You will want to "adjust" the decision code for your site. Other options control the created dataset name format and volume choice. See the NJE initialization operands which start with "DSN" for more details. There are many policy, security, and access control ramifications in the use of these created datasets. Some of our policies include avoiding giving the post office access to users datasets and avoiding charging users for datasets which they didn't create. As a result of this we place the datasets created by the post office under a different high level prefix than the users. Post office options allow you to change this at your site. UCLA/Mail reference (OFCREF) Page 5 We have the post office set to build dataset names of the form: FILE.userid.unique A normal ACF2 rule gives the post office full access to all FILE prefixed datasets. This allows the post office to create the datasets and to delete them as required. A small change to our ACF2 VIO exit allows users read only access to FILE.userid datasets which contain their userid. Bitnet ______ Bitnet is the name for the US part of a global educational and research network which uses the IBM NJE protocols. This NJE network includes VM and MVS nodes (mostly JES2, but some JES3) plus many non-IBM nodes which run software which can talk NJE. In theory it is possible to run an unmodified IBM system, however the native system support usually requires at least some enhancement to attain more than minimal functionality. Actually Bitnet has been too successful -- the NJE network which Bitnet is a part has too many nodes for a standard JES2 system to handle. The standard fix is to change the EQU for $MAXNODE to 4000 (in module $HASPEQU) and then reassemble all of JES2. There's nothing like success! (See USRSRC($MAXNODE)). Bitnet mail connectivity is much wider than just the NJE node list would indicate. Mail gateways allow mail communication between Bitnet nodes and nodes on other networks (which might not use the IBM NJE protocols). Some of these gateways are "official". Others are private as they were created by sites which spanned networks and needed them for their own internal use. Bitnet distributes tables of information on the various parts of the Bitnet network. The OFCBIT program can be used to convert the BITEARN NODES table into a format directly usable by UCLA/Mail. See the section on OFCBIT. Internet (TCP/IP) _________________ The Internet is a collection of networks using TCP/IP and related protocols. NSFnet is one of the well known networks included in the Internet. (ARPAnet used to be one). There are thousands of others. Each network has many hosts (Internet word for node). The design of the TCP/IP protocols allows easy connection of networks in a transparent manner, thus all these networks really appear as one large network. Internet protocols are documented in semi-formal papers called "request for comment" otherwise known as RFCs. Some RFCs are Internet standards while others are proposals or ideas for comment. The beginning of each RFC states if it is a standard. RFCs are all stored at the network UCLA/Mail reference (OFCREF) Page 6 information center (NIC) and can be obtained by any Internet host via FTP (file transfer protocol) which makes them easily available. On Bitnet some RFCs are available from some LISTSERVs. Note that the RFCs are the standards, not this document. See the RFCs for specific details. TCP and IP are the bottom level protocols used in the Internet. There are other higher level protocols, including protocols for mail. Bitnet has adopted some of the Internet standards for mail and mail gateways between Bitnet and Internet exist. The main RFCs for mail formats are: (included in DOCRFC) RFC821 - Simple Mail Transfer Protocol (SMTP) This is the protocol which Bitnet's BSMTP (batch simple mail transport protocol) is built upon. SMTP assumes a real time connection between the two MTAs which Bitnet doesn't have, thus the batch scheme. (See also member BSMTP in OFCRFC). RFC822 - Standard for the Format of Arpa Internet Text Messages RFC822 contains the full syntax of mail headers and addresses. It is suggested that ONLY the syntax charts at the end be relied on as the others in RFC822 are known to contain errors. RFC1123 - Requirements for Internet Hosts -- Application and Support RFC1123 contains updates which correct and supplement the above RFCs. Internet mail addressing and domain name system _______________________________________________ This section gives a brief description of the Internet mail addressing scheme and the Internet domain name system. This is necessary to understand the UCLA/Mail domain name support. This is a simplified version of how the Internet handles mail, for more exact information see the RFCs. A suggest starting place for more information is the first part of RFC1034 "Domain names - concepts and facilities" which is included in the DOCRFC library. Internet mail addresses consist of a left-part and a right-part separated by the character @. The right-part specifies the mail agent (usually something like the node name). The left-part is a parameter to that agent, usually the target mailbox for this message. The left-part content is dependent on the target system. Since some systems mailbox names are case sensitive (upper case and lower case are different) the left part is defined to be case sensitive. The right-part is defined to be case UCLA/Mail reference (OFCREF) Page 7 insensitive (uppercase and lowercase have the same meaning). Note that addresses may have up to 64 characters in each part. With the advent of the Internet domain name system the right-part is a domain name. A domain is an administrative entity which manages a part of the Internet domain naming space. The domain naming space forms a tree structure. A domain name includes from left to right the name of each node in the tree going upward toward the root. The names of the tree nodes are separated by dots. The root of the tree isn't named as there is only one root. The administrator at each level can define hosts anywhere in the part of the tree he owns or can delegate a sub-tree to another administration. sample tree / \ EDU COM / \ UCLA USC / \ / \ OAC CS The above includes the domains: EDU COM UCLA.EDU USC.EDU OAC.UCLA.EDU CS.UCLA.EDU The root domain is owned (administered) by the Internet Network Information Center (NIC) which also owns all the top level domains like EDU. The second level domains are generally delegated by the NIC to the administration concerned with them. For example the NIC has delegated the domain UCLA.EDU to UCLA. The possibility of delegation isn't restricted to just one or two levels. In the above example it would be quite reasonable for CS.UCLA.EDU to be delegated to their department inside UCLA. The domain name system is called a "naming" system. The domain names are names and not locations. The name is related to the administrative authority which authorizes the host to use that name and has NO relation to the physical location of the host or the physical address of the host. In addition to the distributed authority, the actual database is also distributed at the same boundaries. Since the Internet has thousands of networks, each adding and deleting hosts, it would be impossible for any one host to actually know all of the host names. Instead each administration runs a "domain name server" which holds that administrations piece of the whole Internet distribute database. Each administration only has to update its name UCLA/Mail reference (OFCREF) Page 8 server with local domain changes for it to take effect for the whole Internet. The domain name servers answer queries. If the query falls within the administration of that server and hasn't been delegated to another administration then the name server will have the answer and will answer the query. If that area of the domain has been delegated, the domain name server will return a pointer to the domain name server of the administration to which authority was delegated. The issuer of the query will then query that name server. By continuing the above procedure it is possible to find information for any Internet host by starting at the root. Note that the actual implementations include caching techniques which avoid many of the queries which would otherwise be required. Internet mail delivery uses "mail exchanger" (MX) records which are contained in the domain name system. A source mail transport agent (MTA or mailer) queries the domain name system (and follows up on any delegations) to get the MX records for the target domain name (right-part) of the message to be delivered. Each MX record contains the name of a host which will accept mail for the original domain name. The source MTA opens a SMTP TCP connection to one of these hosts and sends it the message. This is a very powerful system as the target mail agent may do more than just place mail in a local mailbox. A mail agent might be a gateway to Bitnet. When it received mail for a domain name which mapped to a Bitnet node it could translate the domain name into the node name and send the results out on Bitnet. The result of this is that the domain name appears to "work" transparently from the Internet side even though the actual mailbox target isn't even on any TCP/IP network. Note that this requires any Bitnet node handled this way to have an Internet domain name and MX record in addition to its Bitnet node name. UCLA/Mail domain support ________________________ The domain support allows the post office to map the domain name into a "place". It then picks a route there and sends the created sysout file to the NJE node specified in the routing information. The domain routing information is necessarily a subset of the distributed domain database. The routing information describes how to send mail to a particular "place". The routing information can include the protocol, node name, userid and other information. See the ROUTE domain statement for complete information. A ROUTE to a gateway would usually specify BSMTP as the protocol and the userid and node names of the gateway. This appears to be in violation of the Internet statements that the domain name isn't related to the location or routing to the host. Perhaps this is, but the post office can't query a domain name server as they don't UCLA/Mail reference (OFCREF) Page 9 exist on NJE networks. In some sense sending the message amounts to a "query" and it also passes the routing problem off to some mail agent which should know better where the mail target really is. This is very similar to the delegation between the name servers and happens at the same administration boundaries. This technique is used on Bitnet to "hide" many hosts behind one gateway machine to the actual Bitnet network. UCLA/Mail doesn't assume that the world only contains one domain tree (the Internet model and the Internet tree). Instead, UCLA/Mail models the world as many trees, with the possibility that some "places" in one tree are the same as "places" in other trees. It does require that each name be unique across all the trees (or that the "roots" of the trees be given explicit names). For example, UCLA/Mail can be told that both MVS.OAC.UCLA.EDU (in the Internet tree) and UCLAMVS.BITNET (in the Bitnet tree) are the same place. Once the post office knows that two names are equivalent it will use either name as appropriate for the destination of the message. Most header addresses will be rewritten ("transmogrified") to be valid in the destination's tree. Thus it will say MVS.OAC.UCLA.EDU to Internet sites, and UCLAMVS.BITNET to Bitnet (or other NJE) sites. UCLA/Mail supports this in general for all nodes defined to it, not just the local node. To accomplish this UCLA/Mail needs not only the name and routing information, but also which "tree" the name belongs to. This "which tree" information is provided by the CLASS number. This number is specified right after the domain name being defined (see the "domain definition statement" section of this document for the syntax). Class numbers also appear in the routing information to let the post office know which "trees" the target node can understand. Typically Bitnet nodes know about the Internet but NOT the reverse. The ACLASS keyword allows a list of classes to be specified as "accepted classes". These list the classes that "place" will accept. The list is used in order so that you can prefer a particular style of name (like the Internet standard) if you want and yet still allow other less preferred classes of name to be used if a name of the preferred class doesn't exist. UCLA/Mail needs definitions of the whole domain space, but doesn't require separate entries for each host (a hopeless undertaking). UCLA/Mail allows defining wild-card domain definitions which are used when no explicit exact match exists. These can fill out the domain name space and provide default routing at various levels. Given a domain name such as FOO.BAR.GORF.EDU, UCLA/Mail searches its tables for FOO.BAR.GORF.EDU (an exact match). UCLA/Mail reference (OFCREF) Page 10 If found then that entry is used. Otherwise it will try *.BAR.GORF.EDU, then *.GORF.EDU, then *.EDU, and finally *. Since the most local is tried first, the lowest level in the tree's routing information will be used. This allows, for example, all Berkeley.EDU hosts to be matched with one entry by specifying *.berkeley.EDU. berkeley.edu does *not* match *.berkeley.edu, this requires a separate berkeley.edu entry. INSTALLATION Prerequisites _____________ * ASMH (V2 preferred) ASMH is the system assembler at UCLA and is required. Version 2 of ASMH is currently installed but is probably not required. The F level assembler will NOT work on the source as is, and may not even with major reordering changes. * UCLA/IPC-370 (on this tape) Interprocess communication is used to send data between MVS address spaces. The current version of UCLA/IPC-370 is V1.410. IPC runs APF authorized, the UCLA/Mail post office does not. * JES2/SP 1.3.0 or 1.3.3 (for NJE) and ACF/VTAM 1.3 (or later) The post office's SNA/NJE interface was developed on these levels of JES2 and VTAM. If the NJE interface is not going to be used then these levels are not important. * WYLBUR (Online Business Systems) The mail system WYLBUR interface is designed for R7 of OBS WYLBUR and allows sending and receiving mail from the WYLBUR active file. For those sites which have obtained the necessary permissions, a second tape is included which contains the interface to the UCLA mail system for OBS WYLBUR. * DFP suggested (or DF/EF) The post office VSAM activity generates VSAM gas which is space in the VSAM cluster which can't be reused. This is much more of a problem without DFP (or DF/EF). A dump/reload of the mail cluster will "release" this gas and is needed periodically. Currently we dump/reload our mail cluster once a week, mostly for performance reasons. As the amount of gas in the cluster increases, the VSAM index increases in size and the records become spread out on the disk. This lowers the probability that a record (including an index record) will be in a buffer. UCLA/Mail reference (OFCREF) Page 11 * ACF2 (optional) The post office user exit supplied makes a call to ACF2 to read LID records to determine if a post office "box" exists (OFCEXIT). The post office is non-authorized but his LID has full scope AUDIT which allows this ACF2 call. If you do not have ACF2 you will need to modify this code to match your installation security environment. * SOF - IBM FDP 5798-CRE (optional) MVS Secondary Operator Facility is used to automatically issue the incremental backup commands to the post office. JES2 automatic commands might also be useable. * ABR - Automatic Backup and Recovery (optional) ABR from Innovation Data Processing is used to backup the post office dump files. It does this automatically as they are changed when used. The ABR job is submitted by SOF. * SCRIPT/VS R3 (optional) SCRIPT/VS could be used to format the documents for other output devices. Mail Installation options _________________________ * non-swap for small OFC and/or IPC memories Due to the intermittent use of the IPC and post office memories, they are swapped out between requests. Every initial request will require that both be swapped (sometimes more than once). Even though it is NOT required that these be non-swappable, it is recommended that for a production mail environment they both be non-swappable. This is especially important to avoiding delays if a check for mail is done automatically at logon. IPC and Mail can be made non-swappable via PPT entries. This requires that the post office modules be in an authorized library even though it is not linked AC(1) or run authorized. We chose to use the same library for both IPC and the post office. * TSO logon auto-mail check This modification intercepts the IBM check for mail in SYS1.BRODCAST and replaces it with a check of the post office. You can easily modify this routine to check both or either as you wish. * NJE interface The post office SNA/NJE interface both sends and receives mail (SYSOUT files). To use this requires the correct level of JES2 and VTAM plus the correct network definitions. * JES2 modifications (Mail routing) This modification routes "mail" destined for the JES2 NJE node to the post office's NJE node automatically. This allows both JES2 and the post office to be known externally as a single NJE nodename. This mod consists of an EXIT13 (TSO/E interactive Data transmission Facility UCLA/Mail reference (OFCREF) Page 12 Screening and Notification) and a source mod (or zap) to JES2 to force EXIT13 to always be called. * JES2 modifications (Nodal message support) There are several JES2 modifications which control routing of nodal messages and process nodal commands. These modifications provide support for issuing creating nodal commands and messages, and for responding or routing to externally issued commands and messages. Some VM system commands are simulated by this code. These are in the NETSRC file along with a TSO CP used to issue nodal messages and commands. See the $README member in NETSRC for more information. * Mail and/or IPC as batch job(s) Both UCLA/Mail and IPC can be run as batch jobs and most of the original testing was done this way. Currently, at UCLA they are both run as STC's (started tasks). Installation ____________ Distribution tape contents __________________________ The distribution tape is standard label and contains both the distribution for UCLA/IPC-370 and UCLA/Mail. The first file of the tape contains the JCL required to load both the UCLA/IPC and UCLA/Mail files. Most of the files after the first are IEBCOPY unloaded partitioned datasets. file 1 DSN=TAPEJCL LRECL 80, RECFM FB, BLKSIZE 6160 (sequential) DOCLIB - combined documentation library (script output) DOCRFC - RFC's and other non-UCLA docs IPCJCL - UCLA/IPC-370 JCL and utility control card library IPCMOD - UCLA/IPC-370 module library IPCMAC - UCLA/IPC-370 macro library IPCSRC - UCLA/IPC-370 source library OFCJCL - UCLA/Mail JCL and utility control card library OFCMOD - UCLA/Mail module library OFCMAC - UCLA/Mail macro library OFCSRC - UCLA/Mail source library OFCPRM - UCLA/Mail parameter library (init/def statements) MSSMAC - UCLA general purpose macro library MSSSRC - UCLA/Mail TSO (not mail cmd) & JES2 source library NETSRC - UCLA/Mail JES2 nodal message modifications & SMTP MODS TSOSRC - UCLA/Mail TSO MAIL command source (and help) TSPLIB - TSO ISPF PANEL library for mail (old) TSMLIB - TSO ISPF MSG library for mail (old) TSCLIB - TSO ISPF CLIST library (old) USRSRC - non-UCLA contributed src/mods Note: Only IPCMAC and IPCMOD are required for post office installation tasks, the other IPC libraries are only required for IPC installation tasks. UCLA/Mail reference (OFCREF) Page 13 The OFCJCL library contains JCL, control statements, and small utilities used in the installation and maintenance of UCLA/Mail. It also contains the SCRIPT input for the UCLA/Mail documents. These will need to be modified to match local conventions. * $ASM - JCL to assemble one OFC section * $ASMALL - JCL to assemble all OFC sections * $LKED - link OFC post office module (OFCMAIN) * $LKEDBIT - link OFC post office Bitnet table utility (OFCBIT) * $LKEDEMO - re-link OFCMAIN for DEMO * $RUNBIT - JCL to run OFCBIT * $SCRIPT - JCL to run SCRIPT * #DEFINE - AMS control cards to define VSAM mail file * #MSERV - JCL for post office (PROC for STC) * DUMP - VSAM cluster dump JCL (1st part of VSAM gas release) * JES2NJE - JES2 definitions required for NJE interface * LOAD - VSAM cluster re-load JCL (2nd part) * OACMODTB - VTAM mode table required for pacing JES2 NJE * OFCCOPY - JCL to run OFCCOPY (batch utility) * OFCBRIEF - script: brief UCLA/Mail overview * OFCSTAT - JCL to run OFCSTAT (batch; see REPORT command also) * OFCCOVER - script: UCLA/Mail cover letter * OFCDISCL - script: UCLA/Mail disclaimer * OFCREF - script: UCLA/Mail reference (this document) * OFCVERS - UCLA/Mail change & version list * VSAMNEW - create post office VSAM mail file (1st time) * VTAMLST - VTAM appl definitions for JES2 and the post office The OFCMOD library is just an assembly and linkage edit of the UCLA/Mail "OFC" source. It may not exactly compare with UCLA/Mail reference (OFCREF) Page 14 your assemblies due to different system (MVS) macro levels, but otherwise it should be identical (different assembly dates too). This assembly was run on a MVS/ESA SP4.1 (or 4.2?%%) system, with SPLEVEL SET=1 for compatibility with older systems (especially non-XA). If your system does not have the SPLEVEL macro you will have to change the OFCSPLVL copy member to comment out the SPLEVEL call to assemble the post office. The TSPLIB, TSMLIB, and TSCLIB libraries contain a very old ISPF application for sending and receiving mail. Some information on this is available in TSOSRC member FULLSCRN. This has been replaced at UCLA by one written by Doron Shikmoni of Bar-Ilan University, Ramat-Gan, Israel. Contact Doron at P85025@Barilan for more information. An alternate full screen user interface to UCLA/Mail is available as BEN (Copyright, Regents of the University of California) which is NOT a part of UCLA/Mail. BEN consists of ISPF Dialog and support routines developed at UCLA to provide a convenient electronic mail interface to users who might not use a computer for any other reason. The emphasis is on ease of learning and use rather than on "power". Contact Pete Nielsen (CSYSPCN@MVS.OAC.UCLA.EDU) for more information. The USRSRC library contains non-UCLA contributed modifications for use with UCLA/Mail. These have not been run at UCLA, but may be appropriate for your installation. Installation tasks __________________ DEMO installation (fast path for DEMO only) ___________________________________________ The following is only suggested as a fast path to demonstrate the post office. It *may* be possible to run the preassembled modules from OFCMOD without reassembly of all the post office routines. For a fast demo most of the local modifications normally required can be skipped or abbreviated. This will allow a look at the mail system in operation without as much effort for as a fully functioning system. Keep in mind that the distributed versions of modules in OFCMOD were assembled on a MVS V4 system. This may be *much* later than your system's version. This may not be all that different however, as I ran the post office assembled on a non-XA system on XA without reassembly. Differences for this "fast path" are marked "DEMO" in the following installation instructions. * load distribution tape (and read documentation) UCLA/Mail reference (OFCREF) Page 15 * install prerequisites This includes UCLA/IPC-370, see the IPCINST document for installation instructions. * allocate non-VSAM datasets DEMO: Skip this step. These datasets are only used when the specific operator command which uses them is issued. They are not needed for a demo. The post office DMPFULL, DMPICR and REPORT files can be allocated at this point and the load library selected. The dump files must be RECFM VB with a LRECL which will hold a post office VSAM record plus a QSAM RDW (2043+4 => 2047). They can have any block size consistent with the region requirements of the post office. Half track (23476) on a 3380 or full track on a 3350 (19K) is suggested. The report file must be RECFM FBA with a LRECL of 133. Any block size which is a multiple of 133 is fine. 6118 will work on both 3380's and 3350's. The load library for the post office can be any library unless a PPT entry is used to make it non-swappable. In that case it must be APF authorized even though the post office does not run authorized. At UCLA the same APF library is used for both IPC and the post office. * allocate VSAM cluster The AMS define statements for the post office VSAM cluster are in member #DEFINE in OFCJCL. These need to be updated to contain the correct dataset names, volume(s), space, and other VSAM options required for your post office file. 10 megabytes of space should be sufficient to start with for a mail file with small size mail limits (<= 50K). At UCLA, our mail file is allocated 2284 cylinders of 3380 space (about 1400 Meg), which contains about 280 to 350 Meg of mail. In a week the VSAM HI-RBA will rise to 750 Meg, so our file is slightly overallocated (so far). Note that our file is on a 3990 controller with cache so the file is allocated NOIMBED, NOREPLICATE. You should specify IMBED and REPLICATE if your file isn't on a caching controller. The file is also allocated REUSE to make a VSAM reorganization easier. This allows reloading the VSAM cluster without having to delete it first. After #DEFINE has been updated, update and run VSAMNEW from OFCJCL. This job deletes any old VSAM cluster and creates a new file with a dummy record to allow VSAM updates to be performed. This dummy record can be deleted by mail delete from a userid which has access to "DUMMYXXX" or by the PURGE command (the dummy message is very old, even though unseen). The simplest is to just UCLA/Mail reference (OFCREF) Page 16 ignore the existence of the dummy record as it won't cause any problems as long as no userid DUMMYXXX exists on your system. * modify post office to local requirements DEMO: Skip this step. All the modules marked with an plus "+" in the post office module list in this document should be inspected for UCLA dependencies. The effects of the following in your environment should also be checked: ACF2 call in OFCEXIT. Userid checks in OFCEXIT. There also exist special checks for various flavors of userid's in the TSO command processors. These UCLA assumptions about userids include: userids are 7 characters the userid is the 1st 7 characters of a jobname C prefix userids are computer center staff CS prefix userids are systems programmers CSYSTEM & CSYSTER are ID's used for major maintenance functions at UCLA. The code avoids restricting these as they must always work. CARPSYS# is the UCLA/ACP (UCLA's old TCP/IP for MVS) running as a batch job. UCLA SVC and UVT (user vector table) references in OFCEXIT. The JCL in OFCJCL($ASM) and OFCJCL($ASMALL) can be updated for your requirements and the modules assembled. non-XA: Member OFCSPLVL in OFCMAC contains a SPLEVEL SET=1 so that the post office can be assembled on a XA system and run on a non-XA system. Each source routine of the post office copies in this member. If your system does not support this macro then you must comment out the SPLEVEL macro call in the OFCSPLVL copy member to avoid assembly errors. * Assemble post office modules DEMO: You can try skipping this step. It may work, however I haven't tested a post office assembled on a MVS V4 system (as shipped) on a pre-XA system (for example). If it doesn't work then you will need to assemble *all* the post office modules. Assembling just some of the post office modules is certain to fail as the system control blocks (DSECT's) wouldn't be consistant. If you make *any* changes then you will need to reassembly everything. Member $ASMALL can be used to assemble all the post office modules or else $ASM can be used to assemble them one at a time. Note: Each logical module of the post office is assembled and linked separately. The unresolved external UCLA/Mail reference (OFCREF) Page 17 names in the linkedits will be resolved when all the pieces are link edited together. (The return codes 4 received by the link edits in $ASM or $ASMALL are normal). * Link edit post office module(s) After the modules have been modified and assembled they can be link edited with members $LKED and $LKEDBIT. DEMO: After running the $LKED link edit, run $LKEDEMO on the output module. This extra link edit replaces the UCLA exits OFCXBOX and OFCXACC in module OFCEXIT with IEFBR14's so that all userids will be considered valid. * post office initialization statements The initialization statements in OFCPRM need to be modified for your installation (and optionally moved to another dataset). If you are not planning on using the UCLA/Mail post office to gateway mail (and rewrite mail headers) then it is suggested that the GATEWAY option be removed from OPT statement. Without GATEWAY specified, NJE source files are must less likely to cause mail loops as they are prevented from being sent back out. See the description of the OPT statement for more information. Note: You will likely need to refer to the original OFCPRM statements, so it's better to run your post office with a different parameter library and just copy the statements you need from OFCPRM. See the section on post office initialization statements for more information. * post office execution JCL (proc if STC) Member #MSERV in OFCJCL is the UCLA STC procedure for the post office. This will need to be modified to point to the post office files at your installation and copied to a proclib (or you can run the post office as a batch job). At this point the post office should be startable but it is not useful without any mail interface. The TSO interface is the easiest one to install first. * TSO command processor The MAIL TSO command processor is contained in the TSOSRC file. See member $INSTALL in that file for specific information. This command has a "DO" subcommand which allows executing other commands under it. Most of the code for "DO" is in module "OACTMP" which is in MSSSRC. DEMO: The mail command must be assembled due do differences between XA and non-XA systems and due to possible different IPC SVC numbers. This assembly UCLA/Mail reference (OFCREF) Page 18 must be done after you have updated member MAISPLVL in TSOSRC and the IPCREQ macro in IPCMAC (see IPCINST instructions for this). DEMO: This concludes the DEMO setup. You should have working local mail from TSO. * TSO logon mail check (optional) This option adds a modification (or exit for TSO/E V1R4 and later) to TSO to perform a "mail waiting" check globally for all TSO users at TSO logon time. This is not required, a user could issue a "MAIL CHECK" command himself (in an initial CLIST for example). This check requires an intercept into the normal MVS/TSO logon mail processing. This intercept point is during logon, before IBM's mail check routine receives control. At this point it is possible to control whether IBM's broadcast dataset will be used for broadcast processing, user mail processing or both. This allows deleting all the users from SYS1.BRODCAST if the TSO SEND command is not going to be used with the LOGON option. At UCLA the send command string in HASPCON has been changed from "',LOGON,USER='" to " ',NOW,USER=('" so that JES2 won't place messages for users into SYS1.BRODCAST. Note that the module installed at this interception point will try to communicate with the post office via IPC. If IPC is not available the intercept will ABEND, if the post office is not available then the intercept will issue the message "Mail temporarily unavailable" after a 10 second delay. See the "IPC initialization at IPL" option in the IPC installation manual (IPCINST) for a way to help prevent this (used at UCLA). Also it is a good idea to be sure that the TSO MAIL CP is actually working (as a test of post office function) before installing this modification. There are three different system environments for this modification, and these require different versions of this logon intercept. The members OACEES73 and OACEESX5 are the two members which make the three different versions required by the different MVS system levels. You should choose the version for the level of your system and them modify it (if required) as described below. You can optionally modify the module to check for both SYS1.BRODCAST mail, notices, or post office mail in any combination. The three different system levels are: Early MVS (including all pre-XA) UCLA/Mail reference (OFCREF) Page 19 For this system level, use the OACEES73 source as a base and remove the AMODE and RMODE statements. The result is linked into the normal MVS/TSO BRODCAST check at logon (IKJEES73). It runs AMODE 24. OACEES73 is then link edited into IKJEES73 in SYS1.LINKLIB with a "postjob". This job installs the OACEES73 intercept whether it is already installed or not. non-XA: On XA OACEES73 must have AMODE 31 as it is linked as the entry of the IKJEES73 load module and passes control to the IBM module which assumes AMODE 31. The AMODE 31 statements may cause a problem on a non-XA system - beware (I can't test this here). MVS/XA (later MVS) For this system level use the OACEES73 source as is. This system level is almost identical to the "early MVS", however the TSO BRODCAST modules run AMODE 31. The same OACEES73 is used, however it is marked AMODE 31 and RMODE 24. The module is then linked into IKJEES73 as in the pre-XA case. MVS (with TSO/E R4) For this system level use member OACEESX5 (an IBM exit name as there is now an exit). This version works slightly differently as the mail check is done before the IBM BRODCAST checks. This avoids having to have both a pre and post LISTBC exits. (Somehow exits make it more complicated. Especially those parameter lists). * NJE interface To use the NJE interface the following is required: 1. The post office initialization statements must include the NJE options. 2. The JES2 initialization statements must include the definition of the post office NJE node. See member JES2NJE in OFCJCL. 3. VTAMLST (VTAM's definition library) must include the definition of both the post offices and JES2's VTAM applications. See member OFCJCL(VTAMLST). 4. A MODETAB entry like OFCJCL(OACMODTB) must exist and be referenced by the JES2 application to allow pacing of the secondary to primary path through VTAM. 5. A COSTAB entry is also suggested if your JES2 will have SNA sessions to places outside of the local MVS system (via a 37XX or CTCA for example). This allows the JES2 VTAM traffic to be given a lower transmission priority than interactive traffic. The COS table entry name to be used by the JES2 sessions should be specified UCLA/Mail reference (OFCREF) Page 20 on the COS= keyword in the MODEENT for the JES2 mode table entry. See the VTAM manuals for more information. * JES2 modification (single NJE name) This modification is used to allow the post office to masquerade to the outside world as the same NJE node as the JES2. Without this mod a node might have to advertise two node names, one for their JES2 and one for their post office. This will work and this modification is not required, however it is not a good idea to run this way on a large NJE network (Bitnet comes to mind) as if everyone did this the number of nodes would double. Since the JES2 node and the post office must have different NJE node names, this modification allows mail addressed to the JES2 node name to be automatically routed to the post office. The biggest problem is deciding what is mail. The decision point is JES2 EXIT13 which isn't supplied much information (it can't look at the contents of the file). At UCLA we decide based on the remote routing and the sysout class of the NJE file. We assume that a "remote" name which isn't valid is really a userid and that the NJE file should then be treated as mail. Some SYSOUT classes are forced to be non-mail so that this routing can be bypassed. The reason for checking the "remote" destination is that VM mail contains the destination userid in the "remote" field which is not likely to be a valid remote. This mod also sets the XWTR field from the remote name. This was thought at one time to be an advantage and may still have some use for the TSO/E RECEIVE command. This modification logically fits into JES2 exit 13. There is only one small problem -- EXIT13 doesn't get called unless the file already has the XWTR field set to the remote userid. SYSOUTs sent by the TSO/E XMIT command or UCLA/Mail will have the XWTR field set. VM systems can set the XWTR field, but it is an option and they may not always set it. This problem can be fixed by a source modification (or zap) to HASPNET. The branches to nop are in HASPNET before label NSRNMJQE. These branches are before the $EXIT 13. They are after checks (CLI/CLC) of PDBWTRID for a leading blank and to see if it is the same as NDHGRMT. This will change HASPNSR to always call EXIT13. To install this modification, inspect and modify as required the member EXIT13 in MSSSRC. Then install it into JES2 with the mod to HASPNET. See also the NJE initialization option SINGLENAME description. UCLA/Mail reference (OFCREF) Page 21 JES2 1.3.4 $NHD MACRO note: In JES2 1.3.4 the $NHD MACRO was changed which resulted in a JOB header length of 256. This is a legal header length but is handled incorrectly at the JES2/RSCS interface. JES2 segments this header into two pieces and RSCS recombines them but leaves the "segmented" flag set. VM APAR VM22917 addresses this problem. Since this problem will exist until *ALL* VM/RSCS sites in the path to any JES2 sites have applied the fix to VM22917, a "temporary" fix has been incorporated in the post office. The post office now generates "extra long" NJE JOB headers such that they always take two segments. This is done by including a user section containing: 'GLORP - ENTIRE NETWORK NEEDS RSCS APAR VM22917' EXEC, INITIALIZATION, AND DEFINITION STATEMENTS The post office EXEC, initialization, and definition statements consist of records which are scanned for tokens. (The EXEC parameter is only one record). Tokens are either keywords, numbers, bit names (flags), or strings (quoted or non-quoted). Numbers can be specified in either decimal or in hex as in assembler syntax. (X'64' is the same as 100). Bit names are just specific names for bits. Strings are either quoted or not. Quoted strings can be used anywhere a non-quoted string may be used. Quotes are required if special characters are to be specified. Quotes in quoted strings must be doubled. Comments can also be entered on a statement by enclosing them between '/*' and '*/'. This type of comments can be continued across record boundaries by placing a - as the last non-blank on each record. In general, statements are read from the post office parameter library (partitioned data set) and only columns 1 through 71 are inspected. Any record with an asterisk in column one is a comment and is printed, but otherwise ignored (including the trailing dash check). Non-comment records may be continued by including a dash '-' as the last non-blank on the record (in 1 through 71). The different post office partitioned data set members have different formats and syntax. Currently there are two types of members: Initialization member (default name OFCINIT) Domain definition member(s) (no default names) UCLA/Mail reference (OFCREF) Page 22 Examples of these option statements can be found in the distributed sample post office parameter library. This sample is from the production post office running at UCLA (UCLAMVS). EXEC parameters _______________ None of the EXEC parameters are required and most are only used for debugging. The post office EXEC parameter format: INIT(string) PARTRCI PARTRCT INIT(string) This specifies the post office initialization parameter member name. The default is OFCINIT. PARTRCI This specifies that the parser (OFCPARSE) is to trace parse "ITEMS" (OFCPAR) entries as encountered. PARTRCT This specifies that the parser (OFCPARSE) is to trace parse tokens as encountered. Initialization statements: (usually in OFCINIT) _______________________________________________ IPC statement _____________ The IPC statement specifies the IPC configuration that the post office is to use to communicate with the mail user agent(s) (like the TSO Mail CP). This statement is required. IPC SVC(number) TAG(string) SVC(nn) The SVC operand specifies the IPC SVC number the post office is to use. The operand is the same number supplied to IPC and is required. TAG(string) The TAG operand specifies the IPC tag string to be used by the post office. The operand is the actual IPC tag string enclosed in quotes and is required. The MAIL UA assumes that the tag specifies 'POSTOFC/MESSAGE'. OPT statement _____________ The OPT statement specifies various post office options. OPT GATEWAY GATE12(var-string) INTBOX(mail-box-prefix) MAXMSG(number) MAXWAIT(number) UCLA/Mail reference (OFCREF) Page 23 MSGOPT(MSGDFR FILEDEL NOERASE) POSTMAN(string) ROUTE822 RWMEMLM(number) SYMDISP STAE TIMEZ(time-zone) TRIMLOCAL GATEWAY This option enables the post office to handle 3rd party mail. Third party mail is mail which is addressed to some other node/host. This mail must be in some MTA-MTA format (BSMTP for now). Without this option mail from "outside" will be failed if it requires a route which isn't local to the post office. This will NOT stop error messages from being returned for mail from non-local hosts. Note: This option is normally used, it can be omitted if no 3rd party mail is to be processed. GATE12(var-string) This option specifies a gateway to be used to generate valid "class 1" addresses from "class 2" address. Usually this would be to generate an Internet address for a Bitnet site which didn't have an Internet name. See the domain name section for more information about address classes. This would cause an address like: user@node.bitnet to appear as: user%node.bitnet@var-string INTBOX(mail-box-prefix) This optional keyword specifies the 4 character prefix to be used to build post office internal mail boxes. The default is "ZZZZ". MAXMSG(number) This specifies the maximum length in bytes allowed for a locally originated message. MAXWAIT(number) This specifies the maximum time in seconds for the post office to wait to avoid S522 abends. The default is 24 hours - 1 second. MSGOPT(option-list) This specifies the following message processing options: MSGDFR This option enables deferred message deletion. With this enabled long messages (multi-record) are not all deleted immediately, but are queued for delete by an asynchronous post office process. Normally specified for a production post office. UCLA/Mail reference (OFCREF) Page 24 FILEDEL This option enables file deletion processing in the post office (see section on post office file processing?) NOERASE This option disables the erase of the physical disk normally done by post office file deletion. The choice of NOERASE or the default of erase is an installation security and performance issue. POSTMAN(string) This required keyword specifies a valid userid on the system which can receive mail and files if file support is enabled. This id *must* exist. FDIR: This keyword sets W#POSTM, but isn't otherwise currently used. It will be used in the future. ROUTE822 This optional keyword specifies that the post office is allowed to route NJE source mail via the RFC822 headers if the mail is NJE addressed to the "MAILER" userid. Use of this option is *not* recommended. This option is not currently implemented. RWMEMLM(number) This optional keyword specifies an internal storage limit for each separate simultaneous post office request. Requests which require more storage than this will fail, usually with the "header too long" error message. A default value is used if this is not specified. SYMDISP This optional keyword specifies that the internal post office global symbol table is to be displayed at initialization time. Used for debugging only. STAE The STAE keyword specifies that the post office should use its ESTAE support. Without this specified, no ESTAE is issued. This keyword is normally specified, except during testing. TIMEZ(time-zone) This specifies the time zone character string to be used when formatting a time. Note that if the middle character is a "D" then the middle character will be selectively changed to an "S" during standard time (USA). FDIR: This doesn't work outside of the USA (and Congress keeps changing the dates for inside the USA), so the future direction is to have a table of time zone offsets and character strings in some post office PARMLIB member. UCLA/Mail reference (OFCREF) Page 25 DEBUG statement _______________ This statement specifies general post office debugging options. DEBUG TRACE(VSAM IPC SEND) ABEND NOWRAP TEST LOGSIZE(number) NOTEID(string) TRACE(trace-options) This specifies which types of trace entries are to be generated. These are printed to the post office log or the internal wrap log. The possible bit names are VSAM, IPC, and SEND. VSAM Trace VSAM cluster requests. IPC Trace IPC requests including all data sent and received. SEND Trace each message SEND including message headers. ABEND This specifies that the post office is to ABEND 111 with a dump at termination. Used only for debugging. NOWRAP This specifies that the post office log is not to be wrapped in storage, but instead is to printed as it is generated. On a production post office this can be a lot of output (depending on the trace options). Used only for debugging. TEST This specifies test mode. This causes WTO's which would normally be "action" type to be made non-action so that the operators don't get excited at a test post office error message. Used only for debugging. LOGSIZE(number) This specifies the size in bytes of the internal wrap trace log kept by the post office. NOTEID(string) Notification prefix for running test post offices. This string (maximum 8 chars) is prefixed to the notifications so it is possible to tell which post office issued a notification. Usually only used on a test post office. UCLA/Mail reference (OFCREF) Page 26 DUMP statement ______________ This statement specifies the post office VSAM cluster dump options. DUMP DSNFULL(dataset-name) DSNICR(dataset-name) DSNFULL(full-dump-dataset-name) This specifies the name (in quotes) of the "full dump" dataset for the post office. Any DMPFULL command dump will be done to this file (via dynamic allocation). DSNICR(incremental-dump-dataset-name This specifies the name (in quotes) of the "incremental dump" dataset for the post office. Any incremental post office DMPICR command dump will be done to this file (via dynamic allocation). PURGE statement _______________ This statement specifies the post office VSAM cluster purge options. (see also the REPORT command). Note that messages to oneself or from "postman" are always considered "seen". PURGE SEEN(number) UNSEEN(number) DSNREPORT(dataset-name) SEEN This specifies how old a "seen" message must be to be purged. Any message "seen" this many days or more ago will be purged during a "purge" command. UNSEEN This specifies how old an "unseen" message must be to be purged. Any message this old or older will be purged during a "purge" command. DSNREPORT This specifies the name (in quotes) of the dataset to contain reports produced by the REPORT and PURGE commands. This file will be allocated via dynamic allocation when it is required. DESTLIST statement __________________ This statement defines a local address replacement text. When the specified local address occurs as the destination of mail, the specified text is logically added to the mail header and any destinations the text contains are added to the destinations for the message. The resulting address can be anywhere that the mail system can address (they are NOT restricted to LOCAL addresses). They can also include other DESTLIST addresses (which would imply another replacement) up to eight levels deep. UCLA/Mail reference (OFCREF) Page 27 DESTLIST entries for POSTMAN and MAILER must be defined as single valid local addresses for normal post office operation. These are "dead letter" drops which should only receive mail on unusual occasions. Mail is trapped here instead of looping forever. Non-local, multiple, or invalid addresses in the DESTLIST mappings for these entries will cause mail loops or exponential growth of the contents of the post office file. These dead letter addresses should be mapped to the person responsible for mail maintenance (or an alternate ID). A DESTLIST entry for POSTMASTER should be made to comply with the Internet standard RFC822. This standard requires that POSTMASTER be a valid local mailbox address at every site. This entry should map to a person responsible for the site's mail system or to a person with responsibility for general site operation. This is an inquiry address for use by other sites. It is also a good idea to define POSTMAST as an eight character version of POSTMASTER (some systems can't say the whole thing). A Bitnet node should also define INFO, and BITINFO entries (also mapped to the same person as POSTMASTER). DESTLIST DEST(string) DATA(string) BLIND DEST This specifies the local destination which is to be mapped by this DESTLIST entry. It is limited to one ATOM (no included dots). DATA This supplies the mail header line to be inserted. This may contain one or more addresses, RFC822 comments, etc. Note that is is required to be a quoted string if any special characters are needed (including @). BLIND This specifies that the added DESTLIST info is not to be visible in the header of the message. Without this specified the line added will have the same visibility as the line containing the DEST address. SYM statement _____________ | NOW: The SYM entries are obsolete and are NOT used by the | post office code. The initialization code has been | retained so that local (non-UCLA) modifications which | use these will still work. These entries make available the address of post office symbol table entries to internal post office routines. Internally, in the post office, symbols in message headers are hashed into a symbol table and the addresses of the UCLA/Mail reference (OFCREF) Page 28 symbol table entries used instead of the symbol character strings. This logic allows the look up of varying length strings of up to 64 bytes long without a long complicated search. Only the 4 byte addresses of the symbol table entries are compared. The symbol pointer table contains slots which point to symbol table entries. These are initialized by the SYM statement. Originally the first 6 symbol table slots were required, additional slots may be used by the user exit module OFCEXIT if required. Slot # use UCLA value 0 my network name 'BITNET' 1 my node name 'UCLAMVS' 2 my user id 'MAILER' 3 "ARPA" 'ARPA' 4 my alternate network 'ARPA' 5 my alternate node 'UCLA-CCN' Note: If no alternate network exists, supply SYM values consisting of dummy values. FDIR: The SYM entries are to be replaced with domain information and will gradually disappear. The syntax of the SYM statement is: SYM SLOT(number) TYPE(number) DATA(string) SLOT(number) This specifies which slot in SL# is to be filled in by this SYM entry. (number is origin zero). TYPE(number) This specifies the type of symbol table entry to be defined. Usually type 1 is used. DATA This specifies the symbol to be added to the symbol table. Note that all symbols in the symbol table are folded to upper case. NJE statement _____________ This statement defines an SNA/NJE interface to the post office. FDIR: Someday the post office might support more than one NJE interface. Each would have its own NJE statement. NJE OPT(START AUTO DSNSTART SINGLENAME) HELO(v-string) UCLA/Mail reference (OFCREF) Page 29 MAILER(string) MYNODE(string) YOURNODE(string) YOURAPPL(string) MAXMSG(number) TRACE(trace-list) DSNPFX(string) DSNUSER DSNSFX(string) DSNUNIT(string) DSNVOL(string) SSREQ OPT(option-list) These are the NJE options. Some of these can be changed via operator commands. START This indicates that an attempt should be made to establish the SNA/NJE connection. (Can also be changed via operator command). AUTO This indicates that if the connection fails it should be automatically restarted when possible. (Can also be changed via operator command). DSNSTART This indicates that the "file" support should be enabled. SINGLENAME This indicates that the post office should change incoming node names which match MYNODE to YOURNODE whenever mail is received. This is to allow advertising only one NJE node name to large networks (like Bitnet). | HELO(v-string) | This required operand specifies the BSMTP HELO string to | be used for outbound BSMTP. | MAILER(string) | This required operand specifies the NJE "userid" which is | to be sent/received as the MAILER for this node. This is | used as the source for BSMTP mail sent and is expected to | be the target userid for inbound BSMTP (or ROUTE822). | The post office does NOT currently support more than one | BSMTP message in a single SYSOUT file. MYNODE(string) This specifies the NJE node name the post office is to use on this NJE session. Note that this is not required to be the same as the NJE name the post office uses in NJE headers. UCLA/Mail reference (OFCREF) Page 30 *** DO NOT call your UCLA/Mail NJE NODE "UCLAMAIL". Pick your own UNIQUE NJE node name. Two sites once both used UCLAMAIL and also managed to get a direct JES2 connection between them. When the JES2-JES2 link failed, JES2 decided that the JES2-UCLAMAIL-JES2 link was the one to use! YOURNODE(string) This is the NJE node name expected by the post office at the other end of the connection. This is JES2's NJE node name. YOURAPPL(string) This is target VTAM APPL for this session. This is the VTAM appl name of JES2 (not the ACBNAME unless they are the same). The post office only supports being the primary end of the VTAM session, thus this is the secondary VTAM APPL name (and JES2 is always the secondary APPL). MAXMSG(number) Maximum length for a message from this NJE connection in bytes. TRACE(trace-list) This specifies the NJE trace entries to be generated for the post office log file (or wrap trace). The following bit names are valid RPL, RU, RID, SR, NDCS, BF. RPL Trace each VTAM RPL completion. RU Trace each RU send/received. RID A higher level trace than RU, as the RU's have been partially processed. SR Sysout receiver traces (OFCXITNJ/OFCNJSR). NDCS Netdata conversion traces (code is currently in OFCXITNJ). BF VTAM interface buffer get/free trace. The following keywords control dataset names generated by the post office for "file" support. These dataset names are of the form: ... UCLA/Mail reference (OFCREF) Page 31 Where , , and are each optional and controlled by the following keywords. DSNPFX(string) This specifies the optional prefix to all dataset names generated by the post office for file support. DSNUSER This specifies the userid is to be included in dataset names generated by the post office for file support. DSNSFX This specifies the optional suffix to be included in dataset names generated by the post office for file support. DSNUNIT(string) This specifies the unit to be used for dynamic allocation by the post office for file support. It can be a specific unit (like 3380), or a generic unit (like SYSALLDA). DSNVOL(string) This specifies the volume to be used for dynamic allocation by the post office for file support. It is generally omitted if the DSNUNIT is a generic unit, otherwise it is a specific volume serial. | SSREQ | This specifies that the post office should use the | destination validation MVS subsystem call to check NJE | node names. This is only needed if the NJENODE operand is | used on a ROUTE domain statement. (See the ROUTE NJENODE | operand). | JES2 V3 requires that callers of destination validation be | in supervisor state. An ABEND S0C2 (privileged operation) | will occur if the SSREQ option is specified on a JES2 V3 | system. | Do NOT specify SSREQ with JES2 V3 without changing | OFCSEND.OFCCKND to issue the IEFSSREQ in the required | mode. | Use of SSREQ is not recommended, it is recommended that | there be a ROUTE statement for each NJE node. The OFCBIT | utility can build ROUTE statements for the BITNET network. VTAM statement ______________ VTAM APPLID(string) APPLID(string) This specifies the post office's VTAM APPL name. This is the VTAM application name of the post office (not the ACBNAME unless they are the same). Currently the post office only supports one session and the post office must always be the primary. UCLA/Mail reference (OFCREF) Page 32 VSAM statement ______________ This statement defines the VSAM options the post office is to use. VSAM LSR(pairs of numbers) OPT(LSR SIS) LSR This describes the LSR (locally shared resources) buffer pool which the post office should build before the post office VSAM cluster is opened. If not specified then no LSR pool will be built. Each pair of numbers is a CI size followed by the number of buffers of that size. OPT This specifies the special VSAM options the post office should use in the ACB for the post office VSAM cluster. LSR This causes the post office to set the LSR VSAM options. This usually requires the specification of the LSR keyword above with values which match the post office VSAM cluster CI sizes. SIS This causes the post office to set the SIS VSAM option (sequential insertion strategy). DOMAINS statement _________________ This initialization statement provides the post office with some domain environment information and points to further post office parmlib members which contain additional domain name information. DOMAINS LOCAL(domain-name) NJENET(domain-name) UNKNOWN(domain-name) MEM(member-name-list) LOCAL(domain-name) This keyword specifies a domain name of this local post office. This is required. This is used by the post office to determine the "PLACE" that represents this post office. This is NOT used to deliver local mail, a ROUTE LOCAL statement is still required to be able to receive ANY local mail. (Note that a pure Bitnet site would specify node.BITNET here). NJENET(domain-name) This keyword specifies the default domain string to be used for mail which has only a single atom in the right-part. (If specified as Bitnet, then user@node would be treated by the post office as user@node.bitnet). UCLA/Mail reference (OFCREF) Page 33 UNKNOWN(domain-name) This keyword specifies the default domain string to be used for mail which doesn't have any right-part and wasn't created locally (local mail defaults to the LOCAL value specified above). MEM(member-name-list) This keyword specifies a list of members which contain domain definition statements. This list is processed in the order specified (which is important as some definition statements are "once only" and ignore multiple definitions). Domain definition statements ____________________________ The domain definition statements describe the routing to places and the preferred address mappings to be used. The order of some of these statements is significant which is an advantage as local definition members can be used to override later common definition members. In particular only the first ROUTE statement specified for a domain name will be used, the rest will be ignored. More information on how this works is in the control block logic section (for those inclined...) ALIAS statement _______________ ALIAS The ALIAS statement causes the post office to treat the first specified domain names as if the second was specified. The post office will NEVER output the first specified domain name in outgoing mail. EQUIV statement _______________ EQUIV The EQUIV statement specifies that two domain names are both names for the same place. If name1 is EQUIV to name2 and name2 is EQUIV to name3 the post office will assume that name1 is EQUIV to name3. Which names are used as name1, name2 or name3 doesn't matter, all refer to the same "place". The may be specified as 0 in which case the class of will be left unchanged. | Initialization now checks that *all* the routes specified | for any names to a single "place" are exactly the same. | EQUIV processing copies any existing route to any name | which doesn't have one, any which already exist are | checked for an exact match. This is different from ROUTE | statement processing as a ROUTE statement for a name which | already has a route will be ignored. UCLA/Mail reference (OFCREF) Page 34 ROUTE statement _______________ ROUTE ... (other stuff) The ROUTE statement defines a route to a place and specifies what classes of address that place will accept. The route information includes the protocol to be used. If more than one ROUTE statement is supplied for the same domain, then only the first is used. The rest are ignored (with a message). This allows overriding "standard" routing information with local site information by placing the local statements in a member processed before the "standard" information. This positional operand specifies the protocol to be used for this route. The following are the currently supported protocols: ERROR This specifies that the mail can't be delivered and an error message should be returned. Usually the MSG keyword is also specified. LOCAL This specifies that the mail is to be delivered locally (to this post office). This implies that the left-part of the address must be some local userid (or DESTLIST) or the USER keyword must be specified. At least one ROUTE LOCAL statement is required to be able to receive ANY local mail, even post office generated error messages. NJE This specifies that the mail is to be delivered to some user at some NJE NODE. This is the standard IBM "punch to the users reader" type protocol. Usually the NODE keyword is used to specify the target network node (but see the NJENODE flag bit). BSMTP This specifies that the Bitnet standard BSMTP protocol is to be used (batch simple mail transport protocol). This requires that the target node and user (actually mailer) be specified by the NODE and USER keywords. | PROFS | This specifies that, if possible, messages are to be | sent in IBM's PROFS format. This is similar to the | NJE protocol except that each data record is shifted | right one column and PROFS header and trailer records | are added. If the source isn't this local node this | protocol is treated as NJE. The NODE, FIUSER, and | LRECL(80) should also be specified. UCLA/Mail reference (OFCREF) Page 35 UCLAXTO This specifies the UCLA X-to/X-from protocol be used. This is only used between the post office and the UCLA/ACP. FDIR: The UCLA/ACP is going away. At that time this protocol support will be removed. NODE(string) This specifies the target NJE node name for the protocols which imply using NJE (NJE, BSMTP, PROFS, UCLAXTO). USER(string) This specifies the target NJE user (or optional local user for LOCAL protocol) for protocols which need or allow one. (LOCAL, BSMTP, PROFS, UCLAXTO). LRECL(number) This specifies the output LRECL to be used. Note that the Bitnet standard is 80 (fixed), however the post office can handle up to 256 (253 for NJE destinations) and can also send/receive variable length records. This defaults to 80 for fixed length or to 253 if RECFMV is specified. Nonstandard values should only be used if it is known that the target site supports it. UCLA/Mail supports both fixed and variable BSMTP. SNN (suppress network node). This is parsed but doesn't do anything. It used to suppress the highest level domain name. (It would make UCLAMVS.BITNET appear as just UCLAMVS for example). RMD (remove duplicate destinations). This causes the send routine to remove duplicate destinations. A duplicate destination is one where both destination "requests" have the following attributes the same: protocol, RECFM, LRECL, RMD flag, NODE, and userid. This is implemented in OFCSEND and is currently not used at UCLA. TRUNC Truncate the left-part to fit it into the NJE header userid field if required. An error is returned instead of the message being sent if this option isn't specified and the left-part doesn't fit in the 8 byte NJE userid field. PRINT This specifies that the NJE output is to be marked as a "print" sysout, instead of the default of "punch". This should be specified if LRECL is set longer than 80 and any VM/RSCS system is in the path on the NJE network. NJENODE This specifies that the NODE value can be filled in from the lowest level atom in the right-part. Useful in "anything.BITNET" type defaults. UCLA/Mail reference (OFCREF) Page 36 *.BITNET definitions are not recommended; use a separate entry for each node. Build the definitions from the Bitnet network node definitione file (BITEARN NODES) using OFCBIT. RECFMV This specifies that the NJE file is to be sent RECFM V (the default is F). This also causes the default LRECL to be 253 instead of 80. | FIUSER | This specifies that the NJE file is to be sent from the | individual userid instead of the Post Office's general ID | (usually MAILER). This can be used for nodes which check | the NJE origin of the file like the Bitnet-VNET gateway. | NJECLASS | This specifies the NJE SYSOUT class to be used. If | omitted than the default NJE class of M is used. MSG(string) This specifies an error message to be used for the ERROR protocol. The string operand usually requires quotes as blank is a special character. ACLASS(list of numbers) This specifies a list of address classes which are accepted by the place this route describes. They are in order of preference from highest to lowest. NET statement _____________ The NET statement is used to set special flag bits in a SVN# (the post office internal representation of a domain name). This is only used under special conditions. NET NODISPLAY NOMATCH NODISPLAY This flag prevents this and higher atoms in the domain tree from being displayed (generated) by the post office. Note that they still exist for all other post office processing. | NOMATCH | This flag sets a bit in the SVN# which used to be tested | during domain name matching. This is no longer used. | NETWORKS | The UCLA/Mail post office interfaces to other networks via | NJE. The post office has an SNA/NJE interface to the | (one) NJE network which allows it to send and receive NJE UCLA/Mail reference (OFCREF) Page 37 | SYSOUT files to arbitrary NJE destinations. It supports | various protocols in these SYSOUT files. | The destinations of the SYSOUTs on the directly | connected NJE network can be the "final" destinations or | they can be servers (mailers) which transfer the mail on | to other networks. The servers can be anywhere on the NJE | network. | On outbound SYSOUTs, the post office can look very | much like a VM node since it builds the NJE headers | itself. On inbound SYSOUTs the post office has the NJE | headers available, however there are cases where it can | not process the inbound SYSOUT successfully. This can | occur for various reasons, the most likely is that the | SYSOUT is over the post office initialization specified | maximum size. Other reasons are possible, including | protocol violations at the NJE header or mail level, or | possibly the post office could be "full". | When the post office NJE receiver fails to | successfully process a SYSOUT it returns a "receiver | cancel" on the SNA/NJE link. This should cause that | SYSOUT to be held for later release and retransmission to | the post office (later when the file isn't full). Since | the SYSOUT will be kept by the sending JES2 until released | (or purged), this allows examination of the failing SYSOUT | which can be very useful for debugging. | When JES2 receives a "receiver cancel" it holds the | "output group" if it is currently sending a SYSOUT, | otherwise it holds the JOB. Unfortuately, the buffering | in the SNA/NJE link between JES2 and the post office | combined with the buffering in the post office implies | that 99% of the time JES2 has already sent the whole | SYSOUT and will thus hold the JOB. If that JOB has only a | single SYSOUT (the one routed to the post office) then it | is effectively held and all is well. If, however, the JOB | has multiple SYSOUTs which are still in the same JES2 | SPOOL, then they are *all* held as the JQE hold is JOB | level. In addition any *future* SYSOUTs from that JOB | *are already held*. | This is particularly a problem with long running JOBs | which spin off SYSOUT files to send mail. One invalid | SYSOUT will cause *all future* SYSOUTs from the same JOB | to be held until released (even if not to the post | office). Both IBM's SMTP and the UCLA/ACP send mail to | the post office via spun SYSOUTs and are affected by this | problem. | I consider the JES2 behavior "non-optimal". It seems | to me that there is *NO* case where holding the JOB is the | correct thing to do, the sysout transmitter should only | hold output groups no matter when the "receiver cancel" is | received. This is like page printer output processing | where output is not purged from the queue even though it's | all been sent to the printer. Since the printer holds UCLA/Mail reference (OFCREF) Page 38 | multiple pages it's possible for a paper jam to lose the | output and thus it can't be considered "printed" until it | passes farther out of the printer. Similarly, the JES2 | sysout transmitter shouldn't purge or hold the "output | group" until it has received "final status" for the JOB | from the other side of the link. OY35414 and OY20887 | describe some of the situations involved with JES2 SYSOUT | processing and SYSOUT holds but don't offer much hope. | In an effort to fix at least part of this problem, | I've made a recent addition to the BSMTP processing code | in OFCXITNJ which prechecks the incoming BSMTP SYSOUT file | for being too large. SYSOUTs which are too large cause an | error message to be sent to *all* the destinations, | source, and the local "postman" id explaining the size | problem. The first 100 lines of the SYSOUT are included. | The SYSOUT is then ignored (accepted from JES2's point of | view), thus the SYSOUT isn't held and other SYSOUTs from | the same job are not affected. | This makes a large difference with IBM's SMTP which | uses the BSMTP protocol to send to the post office. It | doesn't help UCLA/ACP sites as the UCLA/ACP uses the | obsolete UCLA X-to protocol which doesn't have similar | code in the post office. | Other sites have chosen other ways of handling this | JES2 behavior. Some have a JES2 mod (or subtask) which | resets the held output from the post office NODE to local | and then releases it. This allows the TSO/E RECEIVE | command to be used on it. Ask someone who is running this | mod for more information. | BITNET, EARN, Netnorth (etc...) _______________________________ | Bitnet, EARN, Netnorth are all really one directly | connected NJE network. The NJE tables of each node | include all the nodes in the whole network. This is a | world wide network of educational and research | organizations. | This NJE network also contains servers (mailers) which | will gateway mail to other networks. This includes mail | gateways to the Internet. These mail gateways allow | exchanging mail with Internet sites without a direct | connection to the Internet. | There are two files which define the NJE network and | mail environment provided by the network management. You | will need current copies of each of these files: | BITEARN NODES | This file contains NJE, mail and other information about | all the nodes on the NJE network. This file is used as | input to OFCBIT (see next section) in building the | UCLA/Mail OFCPRM domain member DMNNODES. | DOMAIN NAMES UCLA/Mail reference (OFCREF) Page 39 | This file contains mail gateway information for domain | style names (as offered by the gateway owners). This file | is used as input in building the UCLA/Mail OFCPRM domain | member DMNBIT. See MSSSRC(BITNAMES) for the source of a | PLIX program which can be used to process this file. This | function should really be part of OFCBIT (no time so far). | Both dependent UCLA/Mail OFCPRM domain members should | be regenerated from current network definition files | (usually available monthly). | OFCBIT table generation utility _______________________________ | OFCBIT is a batch program used to generate UCLA/Mail | post office "DOMAIN" members from various input file | formats. Currently it supports the BITEARN NODES file | format as input. Use the OFCJCL($RUNBIT) JCL, modified | for your installation to generate new tables. I usually | compare (ISPF 3.13) the new table with the old to get some | sense of what's changing. | Internet (TCP/IP networks) __________________________ | Since UCLA/Mail can only directly connect to an NJE | network, some other product is *required* to pass mail | between UCLA/Mail and a TCP/IP network. This product has | to be on the same NJE network as UCLA/Mail (but does not | have to be on the same NJE node). UCLA/Mail will then | need enough routing information to know which Internet | destined mail should be sent to the TCP/IP interface | product. UCLA/Mail does not need complete domain | information (an impossibility), however it does need | enough information to determine the first hop of the route | (on the NJE network). | The UCLA/Mail routing information used at UCLA is | contained in the OFCPRM dataset. This includes local | routes (DMNOAC), Bitnet routes (DMNBIT and DMNNODES). The | "first ROUTE seen is used" rule is used to override the | Internet routes to the local IBM SMTP (in the DMNOAC | member). Thus DMNOAC contains routes for *.EDU (and other | high level domains) so that local mail doesn't get sent to | the BITNET Interbits, it is just sent directly to SMTP to | be sent on the Internet. | IBM's TCP/IP (& SMTP) _____________________ | Overview of IBM's TCP/IP V1 (& SMTP) | IBM's TCP/IP for MVS is a "port" of their TCP/IP for VM. | I see the following advantages in IBM's TCP/IP: | o It is actively under development (and improving rapidly). | Both new function and improvements in existing function keep | appearing. It's also easy to get the developers attention. | (They're on the Internet!) UCLA/Mail reference (OFCREF) Page 40 | o access to the TCP/IP functions (UDP, TCP etc) from other | address spaces | o source is available | Some disadvantages (which I feel are only short term) | o As a port of the VM product, the performance started out very | poor. This has already (in V1) been much improved. It appears | that the development group is still working on improving it. | o The "core" VS/Pascal code is hard to debug. This is partly | (mostly?) a result of the VS/Pascal compiler not providing | "record" storage maps. IBM appears to be avoiding using | VS/Pascal (in favor of C) for new development, so once the | "core" VS/Pascal becomes more stable this will be less of a | problem. | It does not appear that IBM is going to remove the existing | VS/Pascal code, as much as I would like to see that. | o Some interfaces used on the VM product don't yet have | equivalents in the MVS version. In particular the SMTP NJE | interface doesn't know who sent NJE files it receives (it only | sees the data in the file). | o Performance isn't great (as of V1). Yet. | SMTP (V1) uses an extremely excessive amount of CPU. This is a | direct result of the VM to MVS port/simulation and nowhere near | the actual CPU which is necessary for SMTP to use. I see | nearly a second of CPU for each message (3090J). I have the | feeling that development hasn't gotten around to addressing | SMTP's performance because they have been busy improving the | performance of the rest of the product (IP, TCP, & FTP). | SMTP configuration parameters (for use with UCLA/Mail) | This section discusses the parameters for IBM's TCP/IP | SMTP (V1) when it is to be interfaced with UCLA/mail. | These will be based on the UCLA configuration, there may | be other ways to interface these products. Only the | GATEWAY and MAILER SMTP statements are covered here, you | will still need to configure the other SMTP parameters (or | at least look them over). The UCLA/Mail parameters can be | found in the sample OFCPRM shipped on this tape. | At UCLA, IBM's SMTP and UCLA/mail are used in | combination to form a local Internet-NJE (Bitnet) gateway. | IBM's SMTP performs the actual TCP and domain name server | lookups for sending and receiving mail. UCLA/Mail | performs the header alterations necessary for a gateway in | both directions. | This gateway supports defining Internet style domain | names for a NJE host such that the host appears to have a | valid Internet domain name. The NJE host however, sees UCLA/Mail reference (OFCREF) Page 41 | its own name (NJE node name). Other cases are also | possible, for example Internet style names on both sides. | GATEWAY | At UCLA the SMTP GATEWAY statement is commented out since | I want UCLA/Mail to do the gateway function (and adjust | mail headers). This implies that SMTP will NOT send mail | directly to other NJE nodes on the NJE network. It also | allows running SMTP without a table of all the nodes on | the network (which would otherwise have to be kept up to | date). | A side effect of this is that SMTP will refuse NJE | files from other NJE nodes than the local node. This | assumes that SMTP could tell the NJE source of the | SYSOUTs, unfortunately the MVS version can't. | SMTP MAILER statement | This statement specifies the NJE address of the local | mailer and what type of files it is to be sent. UCLA | specifies: | MAILER MAILER@UCLAMVS NEW LOCAL NJE UNKNOWN | Specify the OFCINIT NJE statement MAILER keyword value as | the userid (MAILER here). | The NJE node value to specify is more complex. Since SMTP | is spinning off SYSOUT files directly into the local JES2 | node, these SYSOUT files don't go through EXIT13, which | thus can't re-route them to the true UCLA/Mail NJE node. | Thus they must already specify the true NJE node name of | the post office. Several possiblities have been | mentioned: | Specify the true UCLA/Mail node name in the MAILER | statement. | This is the simplest. This may cause SMTP to add the | UCLA/Mail NJE node name to the mail headers (possibly | this can be stopped via a modification). Also there | may be cases where some mail (error messages from SMTP) | are NOT sent to this NJE node, but were instead sent to | the local node. So this may not always work. | Specify the local JES2 node name and use a modification to | SMTPQUEU to change the target node name at the last | instant. | This is used at UCLA. (See the list of SMTP | modifications for more information). | Specify the local JES2 node name and use an MVS dynamic | allocation exit to change the node to the UCLA/Mail NJE | node name. UCLA/Mail reference (OFCREF) Page 42 | This sounds interesting (I haven't tried it). This | would also effect other programs (XMIT?) depending on | what was done in the MVS exit. | NEW or OLD | Always specify NEW. All UCLA/Mail versions after V1.420 | support the NEW type of mailer files. See the source | (OFCXITNJ.SMTPCK) for the little documentation what | constitutes the NEW format. | LOCAL or NOLOCAL | Specify LOCAL so that mail will be sent to the MAILER | instead of "directly". Directly means "directly to their | VM reader". That's a strange concept for a MVS system. | (This interacts with the MAILER NJE node specified above). | NJE or NONJE | Specify NJE so that mail for other nodes is sent through | the local mailer first (UCLA/Mail). Actually this may not | matter if you are running without the SMTP GATEWAY | statement. | UNKNOWN or NOUNKNOWN | Specify UNKNOWN so that MX supported NJE hosts mail files | and mail for unknown NJE nodes (assumes GATEWAY not | specified) are sent to the mailer. | UNKNOWN says that SMTP should send files it doesn't know | what else to do with to the mailer to give the mailer a | chance to try to deliver it. This is generally what you | want, with one small exception. If the file came from the | mailer (UCLA/Mail), then sending it back with the same | destination address will result in a looping mail file | between SMTP an