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 and UCLA/Mail. | SMTP contains code to avoid this mail loop. Right | before the mail item is sent to the mailer a check is made | to see if this file was received by SMTP from the mailer. | If it came from the mailer than an error message is | generated informing the originator that the destination | isn't reachable. This error message is sent to the | orginator of the mail item and the undeliverable mail item | is deleted. The only problem with this is that the MVS | version of the NJE spool interface used by SMTP doesn't | supply SMTP with the NJE source of incoming files. This | results in SMTP *never* knowing if an incoming file is | from the mailer. Thus this check will *never* catch a | mail loop. | At UCLA, I've modified SMTPBTCH to check the BSMTP | HELO line to determine if the file is from the mailer. If | it is I set the same flag which SMTP would want set if its | NJE interface had returned useful information. An | alternative is to *always* set the "from mailer" flag for | any file from the NJE interface. This is certainly | simpler and is correct in an environment where all the | files should be from the mailer. Either way requires a | modification to SMTP. UCLA/Mail reference (OFCREF) Page 43 | The other alternative is to run with NOUNKNOWN. The | problem with NOUNKNOWN is that SMTP won't forward mail to | UCLA/Mail unless it "knows" it belongs there. This mode | won't support UCLA/Mail acting as the back half of a | SMTP-NJE gateway. | The point to keep in mind is to avoid introducing | E-mail loops between the post office and SMTP. Always | test both mail which should be delivered by SMTP and mail | which can't be delivered. It's very easy to have only one | case work and the other loop. This test should be made in | both directions. Mail entering from the TCP/IP network as | well as mail from UCLA/Mail. | UCLA SMTP configuration options: | UCLA: | ; GATEWAY ; <-- commented out | NJEDOMAIN BITNET ; pseudo domain name of associated NJE network | ; LOCALFORMAT NETDATA ; local recipients receive mail in Punch format | LOCALFORMAT PUNCH ; local recipients receive mail in Punch format | LOCALCLASS M ; local recipients mail output class | NJEFORMAT PUNCH ; NJE recipients receive mail in Punch format | NJECLASS M ; NJE recipients mail output class | ; | ; mas: set nounknown to avoid SMTP sending outbound files back | ; to mailer when the address isn't valid for Internet; | ; this will cause a reverse problem for inbound ucla/mail | ; 3rd party mail (gateway). | ; AILER SMTP@OTHERSYS NEW NOLOCAL NJE NOUNKNOWN | ; AILER MAILER@UCLAMAIL OLD LOCAL NJE NOUNKNOWN | ; AILER MAILER@UCLAMAIL OLD LOCAL NJE UNKNOWN | ; | ; mas/oac: The following depends on a kludge in SMTP which | ; will cause the mail to actually be sent to node UCLAMAIL | ; instead of UCLAMVS (the local node). | ; MAILER MAILER@UCLAMVS OLD LOCAL NJE UNKNOWN | MAILER MAILER@UCLAMVS NEW LOCAL NJE UNKNOWN | ; | UCLA SMTP modifications (see NETSRC(SMTP----) for the | actual statements: | SMTPBTCH - ServiceReaderMVS *kludge* | Check first "card" for BSMTP HELO and if is HELO | UCLAMVS.BITNET or HELO MVS.OAC.UCLA.EDU then set | TagNodeId to UCLAMVS and TagUserId to MAILER. This | allows SMTP to know when files are from the local | "mailer". | SMTPQUEU - DeliverSpoolFile | If MAILER LOCAL option set and target NJE destination | is MailerNodeid and MailerUserid then change the | destination node to UCLAMAIL. This allows files to | the "local mailer" to really be sent to UCLA/Mail | (which runs as a different NJE node). This is | logically equivalent to the JES2 EXIT13 action. Since UCLA/Mail reference (OFCREF) Page 44 | SMTP is local its NJE files don't go through EXIT13 | and thus can't be rerouted to the post office via | EXIT13. | *** DO NOT call your UCLA/Mail NJE node UCLAMAIL! See | the description of the MYNODE keyword on the NJE | initialization statement. | SMTPEVNT - FixHeader (optional) | Turn off address fixups as UCLA/Mail will be doing | this. (Just set StillInHeader false and return). | SMTP still seems to be generating % addresses. I | haven't had time to look into this and prevent it (I | hear there is an option REWRITE822HEADERS in TCP/IP V2 | which defaults to yes). | SMTPRES - processRQR (optional, special case) | Accept mail for OAC.UCLA.EDU or MVS.OAC.UCLA.EDU as | being local (until UCLA/ACP SMTP goes away -- support | multiple TCP/IP SMTP implementations). | This allows SMTP to know itself by more than one name. | This is useful if you have more than one A record in | the DNS. | Other sites: | Leonard D Woren specifies the actual | NJE node of his copy of UCLA/Mail. He may still have some | SMTP modifications. His SMTP mailer statement looks like: | MAILER MAILER@MVSAMAIL OLD LOCAL NJE NOUNKNOWN | (MVSAMAIL is the NJE node name of UCLA/Mail at USC). | MX gateway note | Using IBM's SMTP and UCLA/Mail as a MX gateway requires | that SMTP accept SMTP mail which isn't addressed to the | local host name. In this case there are MX records in the | domain name system which refer to SMTP's host name. If | there are no other MX records of higher priority than | itself for that host, SMTP will treat that message as | UNKNOWN and will send it on to the mailer (UCLA/Mail) | provided that UNKNOWN was specified on the SMTP MAILER | statement. | There can be loops internal to SMTP if some host is MX'ed | to an DNS A record which points to IBM's SMTP which SMTP | doesn't know about. For example if SMTP is running as | MVS.OAC.UCLA.EDU (128.97.60.16) and someone adds the | following DNS records (anywhere in the world!): | target.dmn.edu MX arec.com | arec.com A 128.97.60.16 UCLA/Mail reference (OFCREF) Page 45 | Now mail sent to target.dmn.edu will be delivered to | 128.97.60.16 which is actually mvs.oac.ucla.edu. SMTP | will look up the MX record for "target" and will see an MX | pointing to arce.com. It will then open a TCP connection | to 128.97.60.16 (itself!) and send the mail. This will | loop. UCLA/ACP ________ The post office interfaces to the UCLA/ACP via NJE. The ACP maintains a JES2 remote via VTAM through which it will accept mail. It will also queue SYSOUT files to the post office NJE node via dynamic allocation. The UCLA/ACP provides the SMTP out-of-band information to UCLA/Mail via "X-FROM:" and "X-TO:" lines. These are prefixed to the RFC822 message header. The "X-FROM:" line is always the first line of a message from the ACP, this is followed by one "X-TO:" line for each recipient. UCLA/Mail prefixes mail routed via the UCLA/ACP with these same "X-" lines for the ACP's use in mail delivery. It then sends this resulting SYSOUT to remote "ARPAMAIL" class M. Note the current UCLA/ACP mail routines assume that the post office will only send one "X-TO" in each outgoing SYSOUT file. | FDIR: At UCLA the UCLA/ACP is being is being replaced with | IBM's TCP/IP product. | IBMIN (& IBMLink) _________________ | At UCLA we have a leased line VTAM link to IBMIN. In | addition to carrying terminal traffic, this line also | carries a SNA/NJE link between our JES2 and IBMIN's NJE | network. This section assumes an NJE connection to IBMIN. | In OFCXITNJ there is a special check for SYSOUTs from | IBMMAIL. These are possible IBM PTF's from IBMlink and | are forced to be treated as files by the post office. | The TSO Mail command has some operands specific for | this use. See the PTF operand on the MAIL LOOK command | (in the help). Mail Gateway ____________ The post office can handle mail as a third party MTA. This is mail which neither starts nor ends at the post office, but only travels through. This allows the post office to be used as a mail gateway between networks. This could be a gateway between a local campus and Bitnet or a general Bitnet/Internet gateway. This type of processing is by default disabled, but can be enabled by the GATEWAY keyword on the OPT initialization statement. UCLA/Mail reference (OFCREF) Page 46 In the unlikely event that you do not require the gateway capability I recommend that this option be left disabled. There are two ways to handle cross network mail addressing, both supported by UCLA/Mail. The best way is if both networks support Internet "tree" domain names. In that case the MX records on one side need to point to a gateway "mail agent", which may have to transmogrify addresses (or not if both networks can use the same ones). An address of: aaa@vm.oac.ucla.edu would result in: aaa@uclavm.bitnet The second way is to use "Gateway" addresses which include the "%" character as a delimiter in the local part of the address. The right-part would address the gateway. The gateway would readdress the mail using the saved real target right-part obtained by backscanning the left-part for the %. As an example, an address of aaa%uclavm.bitnet@mvs.oac.ucla.edu would result in the message being send out on Bitnet with an address of aaa@uclavm.bitnet It is important to change all of the related addresses in the message header in any message which traverses the gateway. This requires sending a different header to each destination of a multi-destination message. See RFC886, "Proposed Standard for Message Header Munging" for more on this subject. As an example, say that a message was sent from UCLAMVS.BITNET (which is also MVS.OAC.UCLA.EDU on the Internet) to several other places. The following "From:" lines might be generated: From: a (local destination, TRIMLOCAL case) From: a@UCLAMVS.BITNET (Bitnet address) From: a@MVS.OAC.UCLA.EDU (Internet style address) OPERATIONS Operator commands (post office) _______________________________ In addition to accepting a MVS STOP ("P") command the following MVS operator modify commands are also valid: UCLA/Mail reference (OFCREF) Page 47 * DMPFULL - Take a full dump of the post office VSAM cluster to a dynamically allocated QSAM file. * DMPICR - Take an incremental dump of the post office VSAM cluster to a dynamically allocated QSAM file. This dumps the key and last updated TOD of all records and the full content of any record updated since the last DMPFULL. * REPORT - Simulate a PURGE of the post office VSAM cluster. Nothing is changed, but the "PURGE" report is generated in the dynamically allocated report file. * PURGE - Purge old messages from the post office VSAM cluster and generate a "PURGE" report in the dynamically allocated report file. * DNJE - Display NJE session status. This command is only accepted if the NJE modules are included. * SNJE - Start NJE session as defined in initialization statements. This command is only accepted if the NJE capability is included and the initialization statements supply the NJE required values. * PNJE - Stop NJE session (normal stop). This command initiates a shutdown of the NJE session. Mail in transit is not complete. If there is a session problem this command may not leave the session in a state in which it can be restarted with SNJE. * CNJE - Cancel NJE session (abnormal stop or cleanup). This command is for use after a PNJE has left the NJE interface in an unrestartable condition. This command will clean up the status and leave it startable (if possible). (Noted in code in OFCNJE as "force close"). * ANJE - Set AUTO mode. This command causes the post office to automatically reestablish a failed SNA/NJE connection. * ZNJE - Clear AUTO mode. This is the reverse of ANJE. | * DSNSTART - Set the DSNSTART option. This allows | restarting file processing (OFCXITNJ.DSETCK) without | restarting the post office. VSAM File Maintenance and Recovery __________________________________ The post office VSAM cluster can be processed by normal AMS functions. Dumps _____ There are three ways to dump the post office file. * A complete dump of the VSAM cluster with the post office down. UCLA/Mail reference (OFCREF) Page 48 This can be done with AMS repro and results in a complete copy of the file since nothing is changing. * A DMPFULL operator command to the post office. This results in a valid logical copy of the file, but is immediately out of date as updates are still happening. It might be possible for an invisible partial message to exist in this type of dump if a send or a delete is in progress when it occurs. * A DMPICR operator command to the post office. This results in a file consisting of the key and last updated TOD of all records in the post office VSAM cluster plus the full content of any record with a last updated TOD after the last DMPFULL. Currently no program exists to use this type of file, however code could be copied from OFCCOPY as a start on building such a program. At UCLA, DMPICR used to be issued every night at 1 AM and the resulting file copied to tape. (This was all automatic, SOF issued the modify to the post office and ABR dumped the file because the change flag was set in its DSCB). Since our file is now 1400 Mbytes (and the actual data is over 300 Mbytes) I've given up on running the DMPICR and DMPFULL here at UCLA. I have run out of disk space for these files. I currently have ABR dump the actual VSAM cluster every night (and keep my fingers crossed). (All 1400M every night). My future plan is to have a "recovery trail" with full recovery capability for the post office. At that point I will dump the full file much less often (weekly or monthly). Message purging _______________ A PURGE is issued every Friday night. This does not require stopping the post office. VSAM reload (& batch processing) ________________________________ Periodically a VSAM dump and reload is performed (once a week). This requires stopping the post office, dumping the VSAM cluster with AMS, and reloading the file with AMS. Note that the file is defined as "REUSE" so that it can be reloaded without requiring it be deleted and redefined. This avoids someone else getting the disk space or the position of the file changing. If old messages marked "deleted" exist they can be deleted by running OFCCOPY on the non-VSAM file before the reload. There should not be many of these, but some can get generated if the system crashes or the post office is stopped while in the middle of a send. The only reason for removing these is to get the space they hold back. UCLA/Mail reference (OFCREF) Page 49 This is usually very small and they can usually be ignored. This technique can be used to delete mail for users which no longer exist (after end of year for example). An alternative would be to just allow such messages to age until the normal purge interval causes them to be deleted. (This doesn't always work. The post office assumes that any mail box which contains mail is valid a user. A user who had left or had his ID removed could still have mail added to his mail box. If he was on a mailing list he would always have "young" mail and the box would never empty.) INTERNALS Post Office module guide ________________________ This is a list and brief description of the modules in the post office. The modules marked with an plus (+) should be inspected for UCLA dependencies. For more information about any of these routines see the source. * OFCBIT - Batch utility to build UCLA/Mail routing tables from BITEARN NODES file. * OFCCMD - This is the operator interface routine. Start, stop, and modify operator command processing starts here. * OFCCOPY - This is a batch utility which runs on unloaded versions of the post office's VSAM cluster. This can be used as a starting point to develop your own batch utilities. This routine is used at UCLA to delete (or "undelete") messages left marked "deleted" which the "purge" command will never delete. This routine is quite old and hasn't been run in a while. Check it out before using... * OFCDMP - This contains the post office's REPORT, PURGE, and DUMP routines. * OFCEXIT + This module is one of the post office user exit modules. The exits available include initialization, termination, access control (several), mail notification, mail routing, and mail protocol routines. The distributed version of this module is the UCLA version of these user routines. Some of these are specific to Bitnet and some are specific only to UCLA. * OFCFILE - This module contains the VSAM I/O subroutines. UCLA/Mail reference (OFCREF) Page 50 * OFCHDR - This module contains subroutines related to message header processing. * OFCINIT - This module contains initialization and termination code. The post office initialization statement tables are in this module. * OFCIPC - This module contains the post office routines which interface to UCLA/IPC-370. Note that the line I/O routines included here have the same interface specifications as others (IPC, MSG, NJE). * OFCMAIL - This module contains the post office's side of the user interface. This is the routine which the TSO command processor (and others) actually communicate with via IPC. * OFCMSG - This module contains logical message and line I/O routines for the post office message processing routines. Note that the line I/O routines included here have the same interface specifications as others (IPC, MSG, NJE). * OFCNJE - This module contains the VTAM interface routines for the post office SNA/NJE interface. * OFCNJSR - This module contains subroutines used by the the NJE sysout receiver logic in OFCXITNJ. * OFCNJST - This module contains the NJE SYSOUT transmitter logic. * OFCNOTE - This module is the "default" OFC notify user routine. It will notify a TSO user (if on) via TPUT NOWAIT/NOHOLD. It is only called by OFCEXIT.OFCXNOTE (a user exit) if called at all. * OFCPARSE - This module contains the initialization and definition statement parsing routines. * OFCSEND - This module is the top level of the "send a message" internal post office logic. It is used by both the UA (user agent) interface (from OFCMAIL) and from other parts of the post office which need to originate messages (like OFCXITNJ). It contains most of the logic for delivering a message. * OFCSTAT - This is a batch utility which reads an unloaded copy of the post office's VSAM cluster and prints some message statistics. (This routine may be obsolete, see the "REPORT" post office modify command). * OFCSUB - This module contains general subroutines used by the post office. * OFCSYM - This module contains symbol table and SVN# (domain name control block) related subroutines. UCLA/Mail reference (OFCREF) Page 51 * OFCTASK - This module contains the post office dispatch and timer services. (The alternate task services have never been used). * OFCTOD - This subroutine converts TOD values to dates and times. * OFCTOKEN - This module contains parse routines used by the post office initialization routine and others. * OFCXITNJ + This module contains the NJE SYSOUT receiver mainline logic. It also contains the NJE input data conversion routines which support subsets of NETDATA and CMS DISK DUMP formats are converted and only on input. The "FILE" (dataset) support is also in this module (that's one huge module --- someday it will be split). The UCLA specific code in this module is mostly in the choices made by UCLA on mail/file processing. Also the file arrival message text is UCLA specific. (This code should "function" elsewhere, it just may not do what you want exactly...) Mail VSAM cluster structure ___________________________ The UCLA/Mail VSAM cluster consists of a single keyed VSAM cluster of variable length records. The logical messages are internally spanned by the post office onto these records thus giving the following advantages: * AMS utilities can be used on the file. * The maximum length of a message is not limited by the VSAM maximum record length. * Buffers for the record (segments) do not have to hold an entire message. Each variable length record has a unique key. The keys consist of: + 0 (8 bytes) - mail box name + 8 (8 bytes) - TOD value when initially added to file +16 (2 bytes) - segment number (origin 0) The mail box name is usually the TSO/WYLBUR userid (logonid). A message is uniquely identified by its handle which is the mail box name and the TOD value. (BOX||TOD) All keys with a box name of X'00' and X'FF' are reserved. box name x'00...1' - control record All keys with a TOD value which has the high 4 bytes equal to zero are reserved. The post office uses generic key search to locate messages in a particular box (possibly after a particular time). UCLA/Mail reference (OFCREF) Page 52 Since messages may be segmented (if long) partial messages might exist in the mail file. Any message which has the "deleted" bit set in the message header of segment zero or doesn't have a segment zero is considered to be invisible as it is a partial message. This is usually used to prevent deletion of a message while copying it to another destination. It is possible for a partial message to exist if the system crashes while a message is being sent or deleted. A batch utility (OFCCOPY) exists for removing these "deleted" messages. The post office assumes that the VSAM cluster is *NOT* shared. Some of the problems which would need to be solved include: * The post office assumes that TOD's are unique and increasing. Duplicate key VSAM errors could occur if the TOD's used were not. Since the TOD clocks on different loosely coupled CPU's are not synchronized they are not unique. They are also not set closely enought to guarantee only increasing values. * No ENQ's are done to protect the file. * All VSAM buffers would have to be flushed on each VSAM request. This would involve substantial extra I/O to the VSAM cluster. * No mechanism exists to notify a recipient if he was logged on to the sharing system. Only one VSAM string is currently used; there is some provision for more than one, but the possible problems and current load have never made it necessary to try more. The LSR buffer pool option does provide a performance improvement as the many GET/PUT's to the same general area of the file find the index (and sometimes data) CI's in the LSR buffer pool. Internally lines are handled and stored as a one byte containing the length-1 of the text following, followed by the text of the line. Zero length lines are not allowed, the maximum length line is 256 bytes of text. This is sufficient with the maximum lengths required. TSO edit limits line lengths (LRECL) to 255 and WYLBUR limits lines to 232. (PDF's limit is 255). The lines of messages are never spanned across the VSAM records. OFC IPC interface _________________ The IPC interface to the UCLA/Mail process is an internal interface. It is not intended to be a general interface. On close study you will find that logical parts of the user interface reside inside of the post office and not in each separate user interface processor. This avoids UCLA/Mail reference (OFCREF) Page 53 duplicate code in each processor and and easily presents a common user environment. There is one additional processor which could use this interface, this is a full screen TSO Mail processor under PDF. This interface is subject to change. A change might require a change to *ALL* users of this interface. Notification ____________ The post office notification routines is OFCXNOTE, a user exit which is in module OFCEXIT. This routine will need to be modified at your installation. At UCLA it is used to notify WYLBUR users (if on) via via an OS modify command. We have an SVC which allows the post office to issue this command without being APF authorized. You will need to remove the WYLBUR code if you need to reassemble this module as it references tables you don't have. Note that TSO users also get notified, this is a result of the call to the default OFC notify routine OFCNOTE from the UCLA OFCXNOTE. *** Beware of OACUVT -- You do have a CVTUSER but it doesn't point to an OACUVT even though the it will assemble. The notify routine also calls the NJE interface via a WXTRN ACON when a message is destined for another node ("way out there"). VSAM gas (non-DFP only) _______________________ DFP or DF/EF is suggested. Without DFP the post office VSAM cluster will fill with gas very quickly. The VSAM I/O sequence will be: (only write-new / erase's shown) write new 'userid||tod001' write new 'userid||tod002' write new 'userid||tod003' write new 'userid||tod004' erase 'userid||tod001' erase 'userid||tod002' write new 'userid||tod005' write new 'userid||tod006' write new 'userid||tod007' erase 'userid||tod005' erase 'userid||tod006' erase 'userid||tod007' Since VSAM before DF/EF will never change the highest key for a CI, the empty CI's get left behind as the TOD increments. These empty CI's cannot be recovered without dumping and reloading the VSAM cluster. UCLA/Mail reference (OFCREF) Page 54 Mail formats (RFC822 and Bitnet) ________________________________ The post office mail formats are guided by RFC822. RFC822 is the standard for the format of Internet text messages. This is "THE" standard which everyone except IBM's NOTE claims that they are following. However, only the Internet community is actually held to this standard. Since UCLA/Mail is required to interface with our VM/CMS systems and Bitnet the post office contains some special checks (extensions?) in syntax to allow non-RFC822 mail to be accepted. For example " at " is accepted in place of "@". The basic problem has been best stated as follows: "On VM, all someone has to worry about to send me a message is to get something of any format dumped into my reader. I (the human) am responsible for figuring out what to do with it from there. I think your mail is going to have to work the same way." In view of this, if a valid local userid exists in the NJE headers of a SYSOUT file, the post office will deliver the message there without requiring the SYSOUT to look anything like mail. It will also "undo" a subset of NETDATA or CMS DISK DUMP format SYSOUTs. SYSOUTs without mail headers will have mail headers generated by the post office from the NJE header information. Mail which is addressed in the NJE headers to the value specified on the NJE statement MAILER operand (usually MAILER) will be inspected for BSMTP format and delivered using the BSMTP information contained in the SYSOUT file. Mail generated by the post office is close to RFC822, however there are some deviations due to local aesthetics, time constraints, and (of course) misunderstandings. | The OPT statement TRIMLOCAL option allows the suppression | of the local domain address on local copies of mail. This | makes all local to local mail contain only simple userids | as addresses. | Example: | To: bbb@uclamvs.bitnet | From: aaa@uclamvs.bitnet | Would be pruned to: | To: bbb | From: aaa | The use of TRIMLOCAL is *NOT* recommended. Without the | TRIMLOCAL option users see the full, real E-mail address. | If this is an Internet Domain name then: UCLA/Mail reference (OFCREF) Page 55 | * A more uniform and universal E-mail addressing scheme | will be visible to users (The Internet domain naming | system). Internet addresses are the same from | everywhere and supported for most systems in the world | today. This will be easier to explain then the current | magic which depends on the system you are sending the | E-mail from as well as the target system. | * A message contained in the body of another message will | contain usable addresses even if sent to another host. | * It will be possible to determine your own E-mail address | by the simple scheme of sending yourself a message. | The TRIMLOCAL option will only affect what is displayed by | the post office, not the addresses accepted. The post office is forgiving in that it passes on unchanged any message header line which it doesn't understand. Addresses which enter the post office from outside without domain names have the NJE "UNKNOWN" domain string added. The Bitnet standard for mail files is class M 80 byte fixed length records. Class N is for diskdump format files and all other classes or formats are only by private agreement between the two ends. In actual practice, anything goes on Bitnet. Mail may contain ":READ" cards (from VM/CMS) or be in NETDATA format. The following RFC822 syntax is not supported by the post office. | * some constructs which cross lines (very few since | V1.425) | * multi-hop routes | Routes are parsed, but only the final target domain | address is used. Thus <@hop1,@hop2:user@domain.there> | results in the mail being sent directly to | user@domain.there. * backslash escape character * square brackets Thus IP address literals are not (yet?) supported. * any blank line is accepted as end of header This is a result of IBM NJE systems not having zero length lines. The "normal" end of header (if generated by the post office is a line of one blank). Postman (and mail loops) ________________________ All of the "return to sender" (error messages) mail generated by the post office is from "postman". To UCLA/Mail reference (OFCREF) Page 56 prevent loops if the error message generates an error message of its own "postman" must be a valid destination which will *NEVER* generate an error message. A simple way to define "Postman" is with a DESTLIST. In some ways "postman" is the "dead letter office". User Exits (OFCEXIT - OFCX....) _______________________________ Most of the UCLA dependent checks are in OFCEXIT. These are the entry points to OFCEXIT which the post office uses to perform basic validity and authorization checks. The distributed OFCEXIT module contains the routines run at UCLA. Some of this code is general, some is specific to Bitnet, and some is specific to UCLA. Some of these "exit" routines are really "inside-out". They are always called to perform their function and they in turn call post office subroutines to do the work. This gives them full decision capability. Note that they are "responsible" for doing the work, they just delegate it to other routines. This means that most changes do not require changes to other post office routines. The following are brief overviews of the post office exit routines. You should look at the source for more information. Especially note the comment block before each routine with entry/exit and description information. (Some routines will refer to other post office routines, if so see their comments too). OFCXINIT - initialization/termination exit __________________________________________ This exit is called at post office initialization after the VSAM cluster is open but before the post office is really "open for business". It is also call at termination before the VSAM cluster is closed. OFCXBOX - validity check mail box name _______________________________________ This exit is called to determine if a mail box name is valid. It is only called if the box is currently empty and may not be called for internally known boxes. OFCXNOTE - local notify exit ____________________________ This exit is called by the post office to perform notifications. (another inside-out exit). This allows alternate notification methods and it may prevent the default mail notification. It may just call OFCNOTE.NOT$NOTE instead to take the default post office action. OFCXUSR - map jobname & userid to true userid ______________________________________________ This exit maps jobnames and userid's to true userid's. Normally this routine will just use the jobname as the userid (1st 7 characters). The main use of this routine UCLA/Mail reference (OFCREF) Page 57 is to support multi-user servers which run as a single job. For example WYLBUR makes requests which all say jobname "WYLBUR", but the userid passed in the request was set by WYLBUR and can be trusted. OFCXACC - message access control exit ______________________________________ This exit controls access to specific mail boxes in the post office. It will not get called in all cases (own mail for example) as there are some early checks in OFCMAIL. One of these early checks prevents the sender from deleting mail which has already been seen by the recipient. There are some special internal post office "userids" which all start with a "<". These are currently only used by the NJE interface and must be allowed to send mail if the NJE interface is to work. OFCXROUT - message routing exit _______________________________ This exit allows the implementation of user mail routing and protocols. It may choose the protocol to be used for each destination for a message. It can use the default internal post office subroutines or locally written routines. OFCXPROT - message protocol exit ________________________________ This exit allows the implementation of user mail protocols. It is called for all mail protocols. It may use the default internal post office protocol routines and subroutines or locally written routines. OFCXVIEW - address view generator exit ______________________________________ This exit generates the address string for a specific address from any viewpoint on the network. It may use internal subroutines provided in the post office to assist it or may use locally written routines. Control Blocks (& Logic!) _________________________ By this point one might be wondering how all this address matching and transmogrification is accomplished. It would seem that each address in the input message must be compared with all the post office initialization and domain definition addresses. This sounds even worse when you realize that the mail addresses are long variable length strings. Actually the post office does very few comparisons especially variable length ones. The basis for most of the comparisons are the post office symbol tables. The symbol tables are hashed look up tables. Each entry is one "ATOM" of an address. The idea is that it is unnecessary to compare the varying length string ATOMs, only the addresses of their symbol table entries need to be compared as the same symbol will UCLA/Mail reference (OFCREF) Page 58 always hash to the same entry. Thus one hash search when adding the ATOM to the symbol table saves every possible later search. During message processing each ATOM in every address in the message is added to a symbol table so that it can be "compared" with the ATOMs in the post office initialization parameters which were added during initialization. Actually it isn't necessary to compare the addresses of the symbol table entries. If the ATOM was defined at initialization time then routing information was chained off of its symbol table entry at initialization time, no additional search is be required to find this information. Otherwise the symbol entry won't have any extra information as it was just created for processing this message. The post office has two symbol tables, one built during initialization and one during message processing. The table built at initialization is permanent and is NEVER altered by message processing. The second symbol table is local to each message send request and is deleted when that request is complete. It is used to hold symbol entries which aren't in the global table. The symbol table routines support using both of these tables as if they were one table. Symbol table control blocks ST# - symbol table root (one for global + one for each local process thread) SY# - symbol table entry SV# - symbol table "value" section; variants SVD# - destlist processing SVN# - domain name processing Mail header processing control blocks: Internally mail lines are processed as varying length lines with a length from 1 through 256. This is stored internally as a 1 byte length-1 followed by the line data. Mail header lines are further processed (especially those containing addresses) and some of the following control blocks are built: HW# - main anchor work area for mail processing (points to chain of HL#'s for each header line) (also implicit parameter for many routines in R6) HL# - represents 1 line of mail header (points to chain of HA#'s for ones with addresses) HA# - represents one token (might be ATOM or other token) UCLA/Mail reference (OFCREF) Page 59 HD# - "fake" token which replaces an entire address thus tokenizing the address to a single item. Points to SVN# for this address (and includes local part of address) The same format is used to hold routing information chained off of the SVN#; these are built exclusively at "global" symbol table build time. SVN# - represents a single domain name (all levels) or a partial domain name (hierarchical) Also some of these are used to represent a "place" Contains pointer to HD# with routing information. Inside the post office mail addresses are parsed and converted to "standard internal format". Each ATOM in the name is hashed into a hash table specific for this mail send request, however the global OFC symbol table is searched first for each ATOM and the global entry is used if found. If not found in the global entry, a local (to this mail processing) entry is made. Upon completion of this process each ATOM in every address of the mail item exists in the hash table. Any names which existed in the initialization parameters will have been found in the global symbol table and the initialization values will be available. The hashed values are used to build a chain of control blocks (SVN#'s) which represent each position in the domain tree. Thus for MVS.OAC.UCLA.EDU there exists an SVN# at the "MVS" level which points up to "OAC" which points up to "UCLA" which points up to "EDU". Note that since there is only one SVN# for MVS which points up to OAC which points up to UCLA which points up to EDU, the address of the MVS SVN# uniquely defines the domain name MVS.OAC.UCLA.EDU; also since the SVN# for MVS was built in the global symbol table as it was specified in the initialization parameters, the routing information for MVS.OAC.UCLA.EDU is chained off of this SVN#. In addition, the Bitnet tree entry for UCLAMVS.BITNET (the SVN# for this) is connected to the MVS.OAC.UCLA.EDU SVN# on its equivalence/alias ring (and since it's a ring they're both on it) so that both sets of names are available. (The ring is not limited to only two SVN#'s). As an aid to comparing SVN#'s to determine if two represent the same "place" a "place" bit exists in an SVN# and one and only one SVN# on the equivalence/alias ring has this bit set (which one is arbitrary; however it's never an alias entry). This makes comparisons trivial, just run around each ring until the "place" is found and then compare the SVN# addresses. If the SVN# storage addresses are equal then the mail addresses represent the UCLA/Mail reference (OFCREF) Page 60 same place, otherwise they are different places. (Subject to the initialization parameters being correct). When it is time to write out the mail header for a destination all the above control blocks are available. The mail header lines are rebuilt from the HA#'s and HD#'s by the SEND routine(s). The SEND routine(s) use the XVIEW subroutine to generate character string mail addresses from the HD#s. XVIEW uses the SVN#'s and other information as needed to select the class of addresses needed by the destination. This includes running around the SVN# equivalence rings to find an acceptable address class for the specified destination of the message. MISCELLANEOUS Additional Information Sources ______________________________ UCLA/Mail Interested party list (LISTSERV list) _______________________________________________ This is a LISTSERV list hosted by Ohio State University. To join the list send E-mail to LISTSERV@OHSTVMA (on bitnet) or LISTSERV%OHSTVMA@ohstvma.acs.ohio-state.edu with a text line of: SUB UCLAMAIL For example: SUB UCLAMAIL Joe Bruin To send a message to the list (to everyone on the list) send mail to: Internet: uclamail%ohstvma@ohstvma.acs.ohio-state.edu Bitnet: UCLAMAIL@OHSTVMA UCLA/Mail developers ____________________ Michael Stein UCLA/OAC Systems (IPC & OFC routines, SMTP) Internet: CSYSMAS@MVS.OAC.UCLA.EDU Bitnet: CSYSMAS@UCLAMVS Peter Nielsen UCLA/OAC Systems (TSO and WYLBUR user agents, BEN, Notebook) Internet: CSYSPCN@MVS.OAC.UCLA.EDU Bitnet: CSYSPCN@UCLAMVS UCLA/Mail reference (OFCREF) Page 61 Others ______ Peter Sylvester GMD (Bonn, Germany) UCLA/Mail400 developer (UCLA/Mail modifications, RACF, JES2 ...) Internet: sylvester@mvs.gmd.de Bitnet: GRZ027@DBNGMD21 Doron Shikmoni Bar-Ilan University, Ramat-Gan, Israel ISPF mail application (JES2, routing tables?) Internet: P85025@MVSA.BIU.AC.IL Bitnet: P85025@BARILAN Leonard Woren University of Southern California (SMTP, JES2, general MVS) Internet: LDW@MVSA.USC.EDU Bitnet: LDW@USCMVSA CICS user agent (none) ______________________ UCLA/Mail does not provide a CICS user agent. This is a result of UCLA/OAC not running CICS. Many sites have asked for a CICS agent, but I don't know of any which has written one. Perhaps by the time you read this one might exist, ask on the network. A CICS user agent would need to provide an editor (or use an existing CICS editor?) for message composition. It would then communicate with UCLA/Mail post office via IPC the same as the other UCLA/Mail user agents. Anyone writing one should look at OFCSRC(OFCMAIL). If you have questions about using IPC or interfacing to the post office via IPC ask away and I'll answer as time here allows. You should also look at the TSO mail command source. X-UR-File definition ____________________ X-UR-File line format definition --- This is the official definition of the X-UR-FILE line as created by the UCLA/Mail post office. Note that this definition may be updated from time to time (usually additions). Line position in the mail header UCLA/Mail reference (OFCREF) Page 62 The X-UR-File line is not guaranteed to be the first header line. It is likely to be the first (or at least near the first). Line format The body of the line consists of positional fields. Each field is separated by one or more blanks from the previous field. The first two positional fields are the created dataset name and the file format. These fields are always present. The basic format of the line is: X-UR-File: /created-dsn/ /file-format/ The fields after the first two (after file-format) are dependent on the file-format. created-dsn This is the dataset the post office has created and cataloged to hold the file. The normal case is that the file will be cataloged and exist. Note that in unusual cases the file might not exist and it may or may not still have a catalog entry. file-format This describes the format of the file. The following strings may appear here: COPY - normal dataset (just copy) DISKDUMP - VM/CMS DISK DUMP command output NETDATA - xmit/receive command format Note that new formats may be added in the future. additional fields (DISKDUMP) What appears after the file format field depends on the file format. Currently only DISKDUMP has more data which is: /recfm-char/ /numeric-lrecl/ recfm-char This is the one character RECFM (F/V/S) (or whatever appears in the DISKDUMP file). numeric-lrecl A numeric LRECL from the CMSN card (at the end of the DISKDUMP file). Samples: UCLA/Mail reference (OFCREF) Page 63 X-UR-FILE: FILE.CSYSMAS.ABCD COPY X-UR-FILE: FILE.CSYSMAS.EFGH DISKDUMP F 80 X-UR-FILE: FILE.CSYSMAS.IJKL NETDATA UCLA/Mail reference (OFCREF) Page 64 INDEX _____ A Additional Information Sources 60 ALIAS statement 33 B Bitnet 5 BITNET, EARN, Netnorth (etc...) 38 C CICS user agent (none) 61 Control Blocks (& Logic!) 57 D DEBUG statement 24 DEMO installation (fast path for DEMO only) 14 DESTLIST statement 26 Distribution tape contents 12 Domain definition statements 33 DOMAINS statement 32 DUMP statement 25 Dumps 47 E EQUIV statement 33 EXEC parameters 22 EXEC, initialization, and definition statements 21 F File Support 3 I IBM's TCP IP (& SMTP) 39 IBMIN (& IBMLink) 45 Initialization statements: (usually in OFCINIT) 22 Installation 10, 12 Installation tasks 14 Internals 49 Internet (TCP IP networks) 39 IP) 5 Internet mail addressing and domain name system 6 Introduction 1 UCLA/Mail reference (OFCREF) Page 65 IPC statement 22 L Local mail 2 M Mail current status 2 Mail design goals 1 Mail formats (RFC822 and Bitnet) 53 Mail Gateway 45 Mail Installation options 11 Mail VSAM cluster structure 51 Message purging 48 Miscellaneous 60 N NET statement 36 Networks 36 NJE connection 3 NJE statement 28 Notification 53 O OFC IPC interface 52 OFCBIT table generation utility 39 OFCXACC - message access control exit 57 OFCXBOX - validity check mail box name 56 OFCXINIT - initialization termination exit 56 OFCXNOTE - local notify exit 56 OFCXPROT - message protocol exit 57 OFCXROUT - message routing exit 57 OFCXUSR - map jobname & userid to true userid 56 OFCXVIEW - address view generator exit 57 Operations 46 Operator commands (post office) 46 OPT statement 22 Others 60 Overview 2 P Post Office module guide 49 Postman (and mail loops) 55 Prerequisites 10 PURGE statement 26 R UCLA/Mail reference (OFCREF) Page 66 ROUTE statement 33 S SYM statement 27 U UCLA ACP 45 Mail developers 60 Mail domain support 8 Mail Interested party list (LISTSERV list) 60 User Exits (OFCEXIT - OFCX....) 56 V VSAM File Maintenance and Recovery 47 VSAM gas (non-DFP only) 53 VSAM reload (& batch processing) 48 VSAM statement 31 VTAM statement 31 X X-UR-File definition 61