Brief: OS/400 includes extensive intersystem communication capabilities, built upon a foundation of APPC and APPN. Display Station Pass-through, PC Support, OfficeVision mail and System Network Architecture Distribution Services (SNADS) are examples of available products and services. This article explains how to implement a simple SNADS configuration that can be used to send messages and spool files between systems.
If you work with more than one AS/400, chances are you've set up communications between the systems. The most common configuration is a dial-up Synchronous Data Link Control (SDLC) line between two systems. A dial-up SDLC line is the easiest configuration to set up and use because it can be created with the ECS modems.
I'm assuming you have an Advanced Program-to-Program Communications (APPC) configuration available. If you don't have an APPC configuration between your two AS/400s, refer to the sidebar, "Configuring a Remote System on the ECS Modem Line."
Creating an APPC configuration between two AS/400s is similar to having a telephone installed at your house when you move. With the telephone, you can participate in basic services with other telephone users. However, to make more advanced use of the telephone line, you need to order additional services from the telephone company (call waiting, call forwarding) or install and configure options that you control (fax machines, computers with modems).
By itself, APPC simply provides a connection between two machines. Additional functions and services can supplement the connection. OS/400 provides many of those services (Display Station Pass-through, object distribution, APPN); other products are available that make use of the APPC services (PC Support, Communications Utilities, OfficeVision).
One useful service provided with OS/400 is System Network Architecture Distribution Services (SNADS). You can use SNADS to send messages, job streams, spool files, database files or save files between systems. Using SNADS is advantageous if you provide programming support for another system, since you can send objects and data between systems. Although it's not necessary to run DSPT concurrently with SNADS, you'll probably work with SNADS from within a DSPT session initially. In fact, SNADS provides the missing "printer pass through" support that most DSPT users need.
Perhaps you've tried and failed to configure SNADS, or maybe you got it to work somehow, but you're not quite sure why. Don't feel too badly; SNADS can be breathtakingly complex to understand. The primary reference manual, Communications: Distribution Services Network Guide, doesn't include much introductory material. But configuring SNADS doesn't have to be difficult. If you follow a few steps, you'll have a working configuration and be in a better position to understand your configuration options.
I'll describe how to configure SNADS so that you can send messages and spool files between two AS/400s. Rather than explain each option in detail, I'll tell you enough about it to get the job done. In future articles, I'll provide additional detail about each configuration decision point.
The Basics of SNADS
Let's trace the process that SNADS uses to send something between systems. First, it verifies that the user requesting the send operation is in fact allowed to send things. Next, SNADS determines where the object is to be sent; it's possible to send multiple copies of the object to the same user or to different users, on the local system or one or more remote systems. Because other distributions might already be in progress, SNADS has a scheduling component, which works similarly to a job queue.
Before actually sending an object to another machine, SNADS verifies that the user that you identified as the recipient exists in the system distribution directory. If the user isn't there, SNADS informs the sender that the distribution can't be sent. If the distribution can be sent, SNADS starts to send it. When transmission completes, SNADS notifies both sender and receiver of the distribution. SNADS must be aware of any communication failures that occur during the sending, so that it can retry the distribution later.
Those are just some of the functions SNADS must perform in order to send objects successfully between systems. Being aware of these factors may help you understand why some SNADS configuration options are required.
I am assuming that you don't have a current SNADS configuration between your machines. If you do (but aren't clear about how it works) you should follow along and create a new configuration. When looked at individually, the configuration options don't readily fall into the big picture. When taken in order, they help you to understand what's required.
What do we need to get a SNADS configuration going? Only a few steps are necessary:
o Obtain a listing of network attributes for each system. o Using the Configure Distribution Services (CFGDSTSRV) command, configure distribution queues. o Also using CFGDSTSRV, configure routing tables. o Use the Work with Directory (WRKDIR) command to add directory entries on each system.
In order to perform the required configuration steps, you need to sign on as QSECOFR or have security administrator (*SECADM) authority on each machine. You'll require an active APPC configuration between the two systems and access to a terminal on each system. An alternative to using two terminals is to use DSPT to access the remote system.
Getting Started: Network Attributes
First, obtain a list of current network attributes for both systems. Surprisingly, even if your AS/400 has never called another AS/400 and the only devices connected to it are dumb terminals, your machine has network attributes and is ready to be linked to other AS/400s.
To get the listing, prompt the Display Network Attributes (DSPNETA) command and select the *PRINT option. Although DSPNETA can be run interactively, it's advantageous to have the printed list available because you're working with two different machines. You'll need the list from each machine.
We use only one value on the listing at this point, although we'll work with several other values later. The value we require is the default local location, or LCLLOCNAME. If your machines' network attributes haven't been changed (with the Change Network Attributes [CHGNETA] command), the local location name is the letter S followed by the machine serial number. You generally won't find it necessary to change this shipped value. However, you might want to change the network attribute for the current system name (SYSNAME on the listing). The current system name, shown in the upper right corner of many OS/400 displays, can help you identify the system you're working on. This system name is useful when you run DSPT, since you might be working on similar displays on the source and target systems.
You can use CHGNETA at any time. If you change any of the network attributes before configuring SNADS, you simply use the new values in your SNADS configuration. If you change the local location name after configuring SNADS, you'll have to update your SNADS configuration. We'll describe that change in a future article; for now, we're working with the current value on the listing.
Working with Configure Distribution Services
The Configure Distribution Services (CFGDSTSRV) command guides you through the steps needed to configure SNADS. Three options are associated with the command. Simply type CFGDSTSRV without parameters and work from the selection display shown in 1. For our SNADS configuration, we'll work with option 1 for distribution queues and option 2 for routing tables.
The Configure Distribution Services (CFGDSTSRV) command guides you through the steps needed to configure SNADS. Three options are associated with the command. Simply type CFGDSTSRV without parameters and work from the selection display shown in Figure 1. For our SNADS configuration, we'll work with option 1 for distribution queues and option 2 for routing tables.
When you select option 1, the next display is Configure Distribution Queues. You use F6 to add a new distribution queue. You're then presented with the Add Distribution Queue display, shown in 2. This display is quite complex, so we'll walk through it step by step.
When you select option 1, the next display is Configure Distribution Queues. You use F6 to add a new distribution queue. You're then presented with the Add Distribution Queue display, shown in Figure 2. This display is quite complex, so we'll walk through it step by step.
A distribution queue is where SNADS places distributions prior to sending them to another system. (Examples of distributions are a message, a spool file or a network file.) For example, you might be working on your local AS/400 when the line to the other system is inactive. Rather than prohibit you from using distribution services, SNADS allows you to queue distributions. When the connection to the other machine becomes available, SNADS can send the queued distributions. This is similar to job or output queues that wait for the availability of a subsystem or spool writer to process entries.
To create a distribution queue, you must enter two fields. The first is the queue name. Unlike other AS/400 object names, distribution queue names can be up to 16 characters long. Because a distribution queue is associated with the target system that you're sending a distribution to, you should assign a name that's indicative of that system. For example, if the current system name from the DSPNETA listing for the target system is CHICAGO, you could also use that as the distribution queue name.
The second field you must fill actually appears as the third parameter on the display, the remote location name. This is the local location name of the target system. It's important that you enter this value correctly, because SNADS will try to send distributions put onto this queue to the system that you specify here. Be clear about this: get the DSPNETA listing for the other system (not the system you are running CFGDSTSRV from), and use the LCLLOCNAME value from that listing as the parameter value.
All other parameters on the Add Distribution Queue display are set to defaults. Several defaults are based on network attributes; if you've made changes to them, you may need to enter additional values on this display. You can safely use the defaults if you haven't changed your network attributes. For now, don't change any of the priority or retry options on the next screen. The default values of these options indicate that SNADS will start sending a distribution as soon as it's placed on the queue, if the communication line is active between the two systems.
After you've entered the queue and remote location names, press Enter. The distribution queue is added to the SNADS configuration. Press F12 to return to the Configure Distribution Queues displays. You should see your newly added queue on the list display. Press F12 to return to the CFGDSTSRV selection display.
Configuring the Routing Table
When you select option 2 (Routing Table) from the CFGDSTSRV display, the next screen contains the Configure Routing Table display. Press F6 to go to the Add Routing Table Entry display, shown in 3.
When you select option 2 (Routing Table) from the CFGDSTSRV display, the next screen contains the Configure Routing Table display. Press F6 to go to the Add Routing Table Entry display, shown in Figure 3.
For system name, enter the local location name of the target system (the same system name that you used in the distribution queue). The group part of the system name isn't used for distributions between two AS/400s; leave it blank. The description parameter is used to describe the routing table entry. You can enter any text you want.
The final four entries that you'll make are the queue name fields in the service level section. Enter the name of the distribution queue that you created four times, once for each of those four fields. Leave the "maximum hops" fields set to the *DFT setting. Press Enter, followed by F12 to return to the previous display.
Although it may seem pointless, there's a great deal of information being described to SNADS on this display. Each of four service levels-fast, status, data high and data low-is used to categorize distributions being sent between systems. You'll generally work with the data high and data low categories; SNADS uses the other two for communications between systems.
What about assigning the same distribution queue name to each of the service levels? A distribution queue is associated with a particular mode description. A look at 2 shows the mode field set to the default value of *NETATR, meaning that the mode is taken from the network attributes. This value appears as DFTMODE on the DSPNETA listing.
What about assigning the same distribution queue name to each of the service levels? A distribution queue is associated with a particular mode description. A look at Figure 2 shows the mode field set to the default value of *NETATR, meaning that the mode is taken from the network attributes. This value appears as DFTMODE on the DSPNETA listing.
A mode is an APPC construct that lets you specify how data should move across your intersystem network. For example, you may have more than one communication line available between two systems. If one of the lines supports a higher speed, it would be appropriate to assign different modes to different distribution queues, which in turn can be assigned to different service levels. (The queue associated with the higher-speed mode is assigned to service levels fast, status and data high. The queue for the lower speed mode is assigned to service level data low.)
Because we're working with only one communication line between the two AS/400s, it doesn't make sense to create additional distribution queues at this point. That's why you enter the same distribution queue name for the four service levels. If you add another communication line in the future, you can create another distribution queue and mode to use the new line. Then change your routing table entry to use the new distribution queue.
Configuring the Other System
Once you've completed the distribution queue and routing table descriptions, go to the other system and repeat the process. This configuration is required if you want to send distributions in both directions. Although the configuration of distribution queues and routing table entries isn't required to receive a distribution, you'll probably find it useful to configure both systems so that they can send to each other. One of the most useful aspects of configuring both systems for distribution is that the target system can return a "received" message to the source system. If the target system isn't configured to distribute to the source system, SNADS has no way to automatically send the confirmation to the source system.
Telling SNADS Who is Sending and Receiving
Now that you've configured the AS/400s, you have to create directory entries on both systems to describe who's sending and receiving. Directory entries are associated with user profiles. These entries are required since every distribution starts with a user and is directed to one or more users on one or more systems.
Directory entries can be the most confusing part of SNADS configuration because you must coordinate the entries between the two systems. Although you can use several options to create directory entries, we'll cover only one option in this article: explicit creation of entries for the sender and receiver on both systems.
The basic rule for directory entries is that you must have a directory entry on the source system for the user profile sending the distribution, and a directory entry on the target system for the user profile receiving the distribution. Also, on the source system you need a directory entry for the recipient on the target system. Although you don't have to include a directory entry on the target system for an originator on the source system, it may be advantageous. That lets you send distributions directly from the target system to an originator on the source system.
Working with WRKDIR
Although the Work with Directory (WRKDIR) command has some parameters, you usually start it by just typing WRKDIR on the command line and pressing Enter. The Work with Directory list display is shown in 4. If you haven't previously added directory entries, the default entries shipped with the system are shown. Don't change or remove those entries; they're used by system functions.
Although the Work with Directory (WRKDIR) command has some parameters, you usually start it by just typing WRKDIR on the command line and pressing Enter. The Work with Directory list display is shown in Figure 4. If you haven't previously added directory entries, the default entries shipped with the system are shown. Don't change or remove those entries; they're used by system functions.
We'll start with adding directory entries on the source system. On the first row of the Work with Directory display, type the number 1 and press Enter. The Add Directory Entry screen, shown in 5, is displayed. The first directory entry we'll create is for a remote user on the target system.
We'll start with adding directory entries on the source system. On the first row of the Work with Directory display, type the number 1 and press Enter. The Add Directory Entry screen, shown in Figure 5, is displayed. The first directory entry we'll create is for a remote user on the target system.
This screen looks complicated, but is really not, as you'll see. The first line, User ID/Address, identifies a user within the system shown on the System name/Group line. The user ID portions can be a user profile name on this AS/400 or another name that you assign to a user. The user ID field length is only eight characters, not ten, so it may not be possible to include user profile names you've established.
The address field can be confusing. Think of this field as "user ID part 2" rather than "address." You can enter the user's surname or another value in this field, such as a department or system that is used. It's important that you give some thought to these first two fields, since they are used with the various send commands to identify the recipients of your distribution.
The problem with these fields is that there may be no easy way to remember them when you want to send a distribution. The send commands don't provide a prompt option. Unless you create programs to supply prompting of directory entries, you have to use some other method to remember the two part identifier. Another problem is that the two part identifier may be confining when you create directory entries for an organization with many users who will receive distributions.
For now, enter a user ID and address that describes yourself, since you want to work through the SNADS sending process. There are additional options and considerations when creating directory entries, but we won't include them in this article.
The next field, description, is used to enter a text description of the user. You can spell out the user's name here and include other information such as a telephone number. This is a required field.
The next two lines contain very important fields. The System name/Group line is used to indicate the system where the user ID resides. For a remote user (the user on the target system who receives distributions), enter his system name in the first field. You'll find this name on the DSPNETA list (the LCLLOCNAME field). You can also press F4 to prompt for the system name field and select the system name from the list of systems known to the source system.
How does your source system get the names of the target systems? From the routing table entry previously described in the CFGDSTSRV command, option 2.
Leave the Group part of this line blank; it's not used when communicating between two AS/400s.
Those are all of the entries required for a remote user. Don't enter the user profile for the remote user. The network user ID is generated by the system. You can fill in the additional information for the remote user, shown on the rest of the display and on following displays. You don't need to change the value for the indirect user field, shown on a subsequent display. (An indirect user is a user that never signs on, but to whom distributions can be sent.)
While you're on the source system, you should also add a directory entry for yourself, as a sender of distributions. Enter your User ID, address and description. The system name field should be set to the current system name; don't change that value and don't enter anything into the group part of the field. You must enter your user profile name on the line below the system name. You can use F4 to prompt for user profile names known to your system. By leaving the system name set to your system and entering the user profile, you've identified yourself to the directory as a local user. Since you're listed in the directory, other people on your system or on remote systems can now send distributions to you. You can continue to enter additional information about yourself, or simply press Enter to add the directory entry.
When you're done on the source system, you should have added at least two directory entries. The first is for the intended recipient, the remote user on the target system. That user could be yourself. For example, if you're programming on both systems, using DSPT to work on the remote system, you can define a directory entry on the source system to send data to yourself on the target system.
The second directory entry you add is for yourself on the source system. That entry is used when you or other SNADS users send data to you.
Repeat this process at the target system. When you add a remote user (remote to the system you're typing on), specify the system name and leave the user profile blank. When you add a local user (local to the system you're typing on), leave the system name set to the default and enter the user profile.
Once you've made the directory entries, you're at the point where you can try object distribution with SNADS.
Distributing and Working with SNADS
Sending a distribution with SNADS is fairly easy, since most of the work with SNADS is done during the configuration. Before trying to send a distribution, verify that your APPC communications line between the two systems is active. Also, verify that subsystem QSNADS is active on both systems by using the Work with Subsystems (WRKSBS) command. QSNADS is included in the shipped system, meaning that you don't have to configure it. You should probably not make any changes to it until you become familiar with SNADS.
The two simplest distributions you can send are network messages and network spool files. We'll see how those distributions are sent. Sending network files is more involved, since you have to receive the file on the target machine.
The two commands that we can try, once communications is up and QSNADS is active, are Send Network Message (SNDNETMSG) and Send Network Spooled File (SNDNETSPLF). Try SNDNETMSG first.
The first parameter of SNDNETMSG is the text of the message. The second parameter is TOUSRID, where you specify the user ID and address you entered as directory entries. TOUSRID is a list parameter; you can send the same message to multiple users. The users can be on your source system or on one or more target systems. For the test, send a message to yourself on both the source and target systems, within the same execution of the command. The message is sent to the message queue associated with the user profiles of both the local and remote users. Since you're on the source system, you can use the Display Message (DSPMSG) command with the message queue name to see the message on the source system, and use DSPT to access the remote system to see the message over there.
The second command, SNDNETSPLF, is almost never run directly from the command line. A better alternative is already included on the Work with Output Queue (WRKOUTQ) display. Execute WRKOUTQ for an output queue that you know has some spool files in it. Option 1 is send. Type a 1 next to a spool file and press Enter. The next display is the command prompter for the SNDNETSPLF command. The only parameter you'll enter here is TOUSRID. Again, you can send the spool file to one or more users on your local or remote systems. The spool file is sent to the output queue associated with the user ID on the target system. When you send a spool file, the original copy remains in the source system output queue.
An additional SNDNETSPLF parameter you should be aware of is the Data Format (DTAFMT) parameter. The default value of *RCD-DATA lets you send the spool file to all systems that support SNADS (S/36, S/38, AS/400s and mainframes). This value doesn't preserve all of the attributes of a spool file. If you're sending spool files to other AS/400s at V1R3M0 or higher, you can use the value *ALLDATA for this parameter to preserve the attributes. If all of your spool- file sending occurs within an AS/400 network, you might want to consider changing the default value for the parameter.
You keep track of SNADS activities with the Display Distribution Log (DSPDSTLOG) command. Whenever a distribution is sent or received, or a configuration change is made to a SNADS object, a journal entry is made to the currently attached QSNADS journal receiver. You can use the Display Journal (DSPJRN) command to view the currently attached receiver, but DSPDSTLOG is much more useful. It formats the SNADS journal entries so that they're more meaningful.
If you're able to do so, you might want to run the Change Journal (CHGJRN) command and generate new journal receivers on both the source and target systems before running a distribution test. This gives you a clean journal on each system. Send a distribution, wait for it to be received on the target and then run DSPDSTLOG on both systems. You can track how SNADS goes about sending the distribution and returning the confirmation message to the sender. Also, if the distribution fails (assuming that you didn't have any communications line failures) the DSPDSTLOG display tracks the source of the failure. Most failures you'll initially encounter will probably occur because of invalid directory entries on the source or target systems.
And Much More!
By now, you should have created the simple SNADS configuration described in this article and have successfully sent messages and spool files. Although the configuration isn't trivial, it's not difficult to do if you break it into small pieces.
We'll describe many more SNADS features in future articles. For example, there are many more ways to set up directory entries, and there's the Send Network File (SNDNETF) command. Although many communication functions are very confusing when first starting out, we'll rapidly build on your knowledge and experience of what happens between two systems.
Craig Pelkie can be reached through Midrange Computing.
ReferencE Communications: Distribution Services Network Guide (SC41-9588, CD-ROM QBKA1B02).
Configuring a Remote System on the ECS Modem Line
To use SNADS between two systems, you need an APPC line configured. If you do not already have such a configuration, you can quickly create one using the communications configuration function of Operational Assistant. Menus and instructions are provided that prompt you through the creation process for the local system. At the conclusion of the process, printed instructions are provided that you use to configure the remote system.
This example assumes that you will be configuring two AS/400s using the ECS modems. Before you start, you need the remote system name and the telephone numbers that are used for both the local and the remote location modems. To get the remote system name, use the DSPNETA command on the remote system and record the value of the "Default local location" parameter (LCLLOCNAME).
Start the process by entering GO CMNCFG at a command line. There are three options on the menu; select option 2 to configure a remote system. On that display, type option 1 in the first line of the list and enter a name to assign to the communications line that will be created. Press Enter after typing the line name.
The next display prompts you for the type of configuration to create. Select option 3, "SDLC switched point-to-point", and press Enter.
You then specify the communications port used. For most ECS modems, this is port LIN011. The next series of displays prompts you for the local system telephone number, then the remote system name, remote system type and remote system telephone number. After entering those parameters, press Enter. The communications line is created and a display tells you to look for the printed instructions that you will use to configure the remote system.
After printing those instructions, you can configure the remote system. On the remote system, use the GO CMNCFG menu and select option 3, "Remote systems using printed instructions". You simply follow the steps given in the printed instructions, entering parameter values as shown.
When you are done, you have a dial-up line created on each system, along with the associated controllers. The line is defined as an APPC line with APPN- capable controllers. That means that you do not have to configure APPC devices for the controllers; the devices are automatically created for you as needed. Simply vary on the line at either system to have it contact the other system. Once the lines, controllers and devices are active, you can start using APPC based functions, such as SNADS and Display Station Pass-through.
Getting Started with SNADS
Figure 1 Initial Display of Configure Distribution Service
Configure Distribution Services Type choice, press Enter. Type of distribution services information to configure . . . _ 1=Distribution queues 2=Routing table 3=Secondary system name table F3=Exit F12=Cancel
Getting Started with SNADS
Figure 2 Add Distribution Queue DisplayAdd Distribution Queue Page 1 of 2 Type choices, press Enter. Queue . . . . . . . . . . . __________ Name Queue type . . . . . . . . . *SNADS__ *SNADS, *RPDS, *SVDS, *DLS Remote location name . . . . Name Mode . . . . . . . . . . . . *NETATR_ Name, *NETATR Remote net ID . . . . . . . *LOC____ Name, *LOC, *NONE Local location name . . . . *LOC____ Name, *LOC Normal priority: Send time: From/To . . . . . . . . __ : __ __ : __ 00:00-23:59 Force . . . . . . . . . __ : __ 00:00-23:59 Send depth . . . . . . . . __1 1-999, blank High priority: Send time: From/To . . . . . . . . __ : __ __ : __ 00:00-23:59 Force . . . . . . . . . __ : __ 00:00-23:59 Send depth . . . . . . . . __1 1-999, blank More... F3=Exit F12=Cancel
Getting Started with SNADS
Figure 3 Add Routing Table DisplayAdd Routing Table Entry Type choices, press Enter. (At least one queue name is required.) System name/Group . . ________ ________ Description . . . . . __________________________________________________ Service level: Fast: Queue name . . . . ________________ Distribution queue name Maximum hops . . . *DFT Number of hops, *DFT Status: Queue name . . . . ________________ Maximum hops . . . *DFT Data high: Queue name . . . . ________________ Maximum hops . . . *DFT Data low: Queue name . . . . ________________ Maximum hops . . . *DFT F3=Exit F12=Cancel
Getting Started with SNADS
Figure 4 Work with Directory DisplayWork with Directory Type options, press Enter. 1=Add 2=Change 4=Remove 5=Display details 6=Print details 7=Rename 8=Assign different ID to description 9=Add another description Opt User ID Address Description _ ________ ________ _ QDOC QDOC Internal Document Owner _ QLPAUTO QLPAUTO Licensed Program Automatic User _ QLPINSTL QLPINSTL Licensed program install _ QPGMR S1034786 QPGMR Directory entry _ QSECOFR MC.DST Product Distribution _ QSECOFR QSECOFR Security Officer _ QSYS QSYS Internal System User Profile _ QTCP QTCP IBM User created to support SMTP restart _ QUSER QUSER Default user for PC Support _ RCVOBJ MC Receive object handler on MC production system _ RCVOBJ MC PGMR Receive object handler on MC PGMR development sys. _ RCVOBJ MC SHIP Receive object handler on MC SHIP shipping system More... F3=Exit F5=Refresh F9=Work with nicknames F10=Search directory F12=Cancel F13=Work with departments F17=Position to F24=More keys
Getting Started with SNADS
Figure 5 Add Directory Entry DisplayAdd Directory Entry Type choices, press Enter. User ID/Address . . . . ________ ________ Description . . . . . . __________________________________________________ System name/Group . . . MCPGMR__ ________ F4 for list User profile . . . . . __________ F4 for list Network user ID . . . . _______________________________________________ Name: Last . . . . . . . . ________________________________________ First . . . . . . . . ____________________ Middle . . . . . . . ____________________ Preferred . . . . . . ____________________ Full . . . . . . . . __________________________________________________ Department . . . . . . __________ F4 for list Job title . . . . . . . ________________________________________ Company . . . . . . . . __________________________________________________ More... F3=Exit F4=Prompt F5=Refresh F12=Cancel F14=Add X.400 O/R name F18=Display location details