Brief: In a previous article, we showed how to configure SNADS so you can send spool files and messages between two systems. This article shows how to send save files and database files with SNADS. Although you use all of the same SNADS components-distribution queues, routing entries and directory entries- there are several additional commands and concepts you need to know.

You can do many things with an APPC connection between AS/400s. One very popular and useful function is Display Station Pass-through (DSPT), which allows you to sign on to another system as if you were connected to it. In "Getting Started with SNADS," MC, May 1994, I showed you another way to use an APPC connection. The article explained how to configure System Network Architecture Distribution Services (SNADS) over an APPC connection to send spool files and messages between systems. With SNADS, you can also send save files, database files and job streams.

Once you have a SNADS configuration between two machines, sending messages and spool files is simple. However, database files and save files require the use of several commands in addition to the appropriate send command. This is because when the files reach the target system, each file must be received and objects in save files must be restored before they can be used.

I'll work through two examples of how file objects are sent with SNADS. In the first example, I use the Send Network File (SNDNETF) command to send a single member from a physical file. In the second example, I save several objects to a save file and then send that. I assume that you have a working SNADS configuration between two AS/400s. If not, you'll need to set that up before working with the examples. (See "Getting Started with SNADS," MC, May 1994.)

Overview of File Send and Receive

Four commands are used to send and work with files in a SNADS network.

o Send Network File (SNDNETF): used to specify the file and member to send and the recipients of the distribution (the sent file).

o Receive Network File (RCVNETF): required because (unlike spool files and messages) database files and save files sent with SNADS have to be received on the target system. You can send a file between systems; but until you receive it, you can't work with it as a database file or save file.

o Delete Network File (DLTNETF): used if a network file was sent to your system and you don't want to receive it. Rather than receive the file and then delete it, you can delete it while it is still a network file.

o Work with Network File (WRK-NETF): provides a panel that you can use to receive, delete or display the contents of a network file. WRKNETF also provides an outfile capability, so you can use it in a program to automate network file processing.

Sending a Single Member

The simplest way to use SNADS to send a database file is with the SNDNETF command, specifying the file name and the user ID of the intended recipient. By default, the command sends the first member. You can send a single physical file member to one or more users, who can be on remote systems or on your local system. This is consistent with other SNADS send commands, but it is unclear why you would send a file to a user on your local system.

You have to be aware of some considerations when sending files. Possibly most troublesome is that, when the file is sent with SNDNETF, SNADS does not send the external definition. After the file is successfully sent, you must receive the file on the remote system using RCVNETF. Normally, the RCVNETF command is used to receive the file into a preexisting file of the same format. If you need to send the definition with the file, you must save the file to a save file and send that.

Another concern is that you can't send a file that contains null fields, defined with the ALWNULL DDS keyword. If you need to send a file that contains null fields, you'll have to copy the data to another file, dropping the null fields. Then, send this file and reconstruct it on the target machine.

You must also consider the size of the files you want to send. The file (object) cannot be larger than approximately 2GB. If you are sending a file to a pre-V2R2M0 AS/400, the file must contain 16,777,215 or fewer records. Both the sending and receiving machines need enough available disk space to contain a copy of the file being sent. If your disk usage is near, or has exceeded, the auxiliary storage threshold for the sending machine, you may get message CPF8068, return code 0010, indicating that the threshold is exceeded on the server machine (your local system).

Despite these concerns, the SNDNETF command is not difficult to use. The only information you need to enter is the file name and users to whom the file is to be sent. You need to specify a member name only if the member to be sent is not the first member of the file.

How SNADS Handles Distributions

What happens after you issue the SNDNETF command depends upon the status of the QSNADS subsystems on the source and target machines and the distribution queues on both machines. 1 shows the conditions that might exist on the source and target machines. Assuming proper SNADS configuration on both machines, the only two factors that you must control are the status of the QSNADS subsystems and the status of the distribution queues.

What happens after you issue the SNDNETF command depends upon the status of the QSNADS subsystems on the source and target machines and the distribution queues on both machines. Figure 1 shows the conditions that might exist on the source and target machines. Assuming proper SNADS configuration on both machines, the only two factors that you must control are the status of the QSNADS subsystems and the status of the distribution queues.

A complete distribution happens only when QSNADS is active on both systems and the distribution queues are in a "waiting" status on each system. A complete distribution includes the following six elements-anything less is not a complete distribution:

1. Message to the sender. 2. The distribution being sent through the distribution queue. 3. Distribution log entries. 4. The "received" message on the target system. 5. The distribution being placed on the network file queue on the target system. 6. The sending of a confirmation message from the target back to the source.

SNADS will complete the distribution as soon as the resources become active and ready. For example, if QSNADS is inactive on the source machine, you can still use SNDNETF to send the file. However, because QSNADS is inactive, the distribution doesn't go anywhere. It stays put until SNADS becomes active; then the distribution is sent.

If you're just starting to work with SNADS, make a point of having QSNADS active on both systems and the distribution queues on each system in a "waiting" status before sending anything. This will eliminate a potential source of confusion during your initial transmissions. Because a file must be explicitly received, it may not be immediately obvious whether the transmission failed or the file was not received by the recipient. (The next section explains the possible messages and what they mean.) By ensuring that QSNADS is active and the distribution queues are waiting on both systems, you'll have a simple test case-later you can change the status of any component to observe the effects.

Receiving a Network File

Assuming that everything is set to make a complete distribution, how do you know SNDNETF is complete? On the source system, you have two ways to verify that the file is completely sent. If you want to look at distributions from many users, you can use the Work with Distribution Queue (WRKDSTQ) command to see the status of distributions sent by any user. The WRKDSTQ command initially presents a list of all distribution queues on your system. Select the queue you would like to work with (option 5) and you'll be presented with the Work with Queue Entries panel. A distribution entry in the process of transmission has a status of "sending." After the distribution is sent, it disappears from the distribution queue.

Alternatively, you can display the message queue of the user that sent the file. When the file is received, message CPI8070 ("File xxx received...") is sent. On the target system, a similar message (CPI8050) is sent to the message queue of the user designated as the recipient, indicating that the network file has arrived. The file must still be received with the RCVNETF command.

Once that message reaches the target machine, you can use the WRKNETF command to work with the network file. An example of the WRKNETF display is shown in 2.

Once that message reaches the target machine, you can use the WRKNETF command to work with the network file. An example of the WRKNETF display is shown in Figure 2.

At this point, the file resides on the target system but cannot be used as a database file. First, you must use the RCVNETF command, or option 1 on the WRKNETF display, to receive the network file into a database file on the target machine. (Option 1 executes the RCVNETF command with many of the parameters defaulted.)

If you use WRKNETF option 1 with the default parameter values and don't prompt it, the file is received into the corresponding file on the library list. If the file exists in more than one library, the received file may end up in a library other than the one you intended. For example, 2 shows that we're receiving an RPG source member for file QRPGSRC. With option 1, the library list is used to locate the first occurrence of file QRPGSRC. If the member doesn't exist in the database file, it is added. Records in an existing member are replaced, so be careful when using the defaults.

If you use WRKNETF option 1 with the default parameter values and don't prompt it, the file is received into the corresponding file on the library list. If the file exists in more than one library, the received file may end up in a library other than the one you intended. For example, Figure 2 shows that we're receiving an RPG source member for file QRPGSRC. With option 1, the library list is used to locate the first occurrence of file QRPGSRC. If the member doesn't exist in the database file, it is added. Records in an existing member are replaced, so be careful when using the defaults.

A good idea is to prompt option 1 with the F4 key so you can specify the qualified name of the file and member to receive it in. You can also choose to add or replace records in an existing database file.

If you use the RCVNETF command instead of WRKNETF, you may also have to specify the file sequence number. As shown in 2, you can have multiple network files with the same file and member names. These network files are distinguished by the file number assigned to them when they arrive on the target system.

If you use the RCVNETF command instead of WRKNETF, you may also have to specify the file sequence number. As shown in Figure 2, you can have multiple network files with the same file and member names. These network files are distinguished by the file number assigned to them when they arrive on the target system.

Sending Multiple Objects

The SNDNETF command is easy to use for sending a single physical file member. But you might want to send many other types of objects. For example, if you develop and maintain software at a central location for a number of other sites, you might have to send compiled programs, display files, data areas and other types of objects. To send those objects, you must first place them into a save file and then send and receive the save file. A summary of the steps required is shown in 3.

The SNDNETF command is easy to use for sending a single physical file member. But you might want to send many other types of objects. For example, if you develop and maintain software at a central location for a number of other sites, you might have to send compiled programs, display files, data areas and other types of objects. To send those objects, you must first place them into a save file and then send and receive the save file. A summary of the steps required is shown in Figure 3.

Saving objects for transmission through the network is no different than a normal save to a save file. You first create a save file or clear an existing save file. Then, you use the SAVLIB or SAVOBJ commands to save one or more objects to the save file. SNDNETF requires that you save all of the objects that you want to send with one save command-you cannot do more than one SAVLIB or SAVOBJ command to the save file.

When you have the objects in the save file, you can use SNDNETF to send the save file. SNADS processes this the same way it processes the transmission of a single physical file member.

Receiving Multiple Objects

On the target system, you need to receive the save file with RCVNETF or WRKNETF. Before receiving the file, a target system save file must exist. After you receive the network file into the save file, you can use the Restore Object (RSTOBJ) or Restore Library (RSTLIB) command to restore objects from the save file to the required library on the target system. Finally, you can optionally delete the save file.

When you send objects with a save file, be aware that you may be unable to restore the objects on the target system. For example, if you save a logical file but not its corresponding physical file, and if the physical file doesn't exist on the target system, the logical file cannot be restored. Also, if an object is sent within a save file and the receiving user does not have sufficient authority to the object, it won't be restored. These considerations are not the result of any SNADS restrictions, but rather just the normal save and restore considerations. SNADS simply provides the transport of the save file to the destination.

Tracking What Happened

With any of the SNADS send commands, you can send a distribution (message, spool file, database file or save file) to one or more users on one or more systems. To find out what happened to those distributions, use the Display Distribution Log (DSPDSTLOG) command. DSPDSTLOG formats and displays journal entries that SNADS writes to the QSNADS journal. You can also use the Display Journal (DSPJRN) command to view these entries, although it doesn't present the journal entry data in as meaningful a way. You would use DSPJRN if you wanted to get the journal entries into a database file for use in a program.

4 shows a sample DSPDST-LOG display. These entries are the result of one SNDNETF command. When you review distribution log entries, you should view them in date and time order within sequence number. The sequence number is used to group entries for a related transaction.

Figure 4 shows a sample DSPDST-LOG display. These entries are the result of one SNDNETF command. When you review distribution log entries, you should view them in date and time order within sequence number. The sequence number is used to group entries for a related transaction.

In the figure, the entries for sequence number 0026 were generated on the source system. The *ORG entry indicates that a distribution originated on the source system. The entry details (which you can display with option 5) include the qualified name of the job which originated the distribution; the date, time, user and system name; the object size; the number of destinations; and, optionally, the destination user IDs (use F10). The *RTR entry is used to show that the source system successfully routed the distribution. That means that SNADS knew where to send the distribution because a valid directory entry was found on the source system. The last source system entry, *SND, means that SNADS sent the distribution.

The three entries for sequence number 0022 were generated by the target system. These entries result from the confirmation message sent by the target system back to the source system to indicate receipt of the distribution. The first entry, *RCV, means that the source system received a distribution (that's the confirmation message). The details in this entry contain the originator and system name of the target system so you can see where the message came from. The *RTR entry means that the confirmation message was routed back to the source system user who initiated the send process. Finally, the *ARV entry indicates the confirmation message was delivered to the source system.

Confirmations are only one level deep-in other words, when you send a distribution to another system, that system returns a confirmation that it received the distribution. That's as far as it goes; the source system does not, at that point, send a confirmation that it received the confirmation.

Closing Out

Sending and receiving files and objects with SNADS isn't especially difficult, once the SNADS environment is properly configured between two machines. It may be easier to think of this as simply another way of doing a save and restore process. The SNADS commands that you use-SNDNETF, WRKNETF and RCVNETF-are simply intended to tell the source machine where to send the distribution and to enable the target machine to receive the distribution in a controlled manner.

Although the capability of sending database files is important when you need to transport data, the save file capability makes SNADS ideal any time you maintain different machines from a central site. With the save file, you can package programs, source code, files, commands and other objects needed at the remote location. After sending them, you can use DSPT over the same connection to set up the objects on the target system.

In upcoming articles, we will look at other SNADS features-especially the distribution directory and directory shadowing-and review how SNADS sends distributions in both APPN and non-APPN networks.

Craig Pelkie can be contacted through Midrange Computing.

Reference Communications: Distribution Services Network Guide (SC41-9588, CD-ROM QBKA1B02).

Sending Files with SNADS

Figure 1 How SNADS Handles Distributions

 Machine QSNADS Dist Queue Result Source Active Waiting Message indicates file was sent Distribution log entries: *ORG - distribution originated *RTR - distribution routed *SND - distribution sent *RCV - "received" message from target *RTR - "received" message from target routed *ARV - "received" message from target arrived Entry is on distribution queue as "sending" Target Active Waiting Message indicates file was received Distribution log entries: *RCV - distribution received *RTR - distribution routed to receiving user *ARV - distribution arrived *ORG - confirmation message originated *RTR - confirmation message routed to sender *SND - confirmation message sent to source Confirmation message sent back to source File can be used with WRKNETF/RCVNETF Source Active Waiting Message indicates file was sent Distribution log entries: *ORG - distribution originated *RTR - distribution routed *SND - distribution sent Entry is on distribution queue as "sending" Target Active Held Message indicates file was received Distribution log entries: *RCV - distribution received *RTR - distribution routed to receiving user *ARV - distribution arrived *ORG - confirmation message originated *RTR - confirmation message routed to sender Confirmation message held on HIGH dist queue File can be used with WRKNETF/RCVNETF Source Inactive N/A Message indicates file was sent *ORG entry in distribution log Entry not on distribution queue Target N/A N/A N/A Source Active Held Message indicates file was sent *ORG and *RTR entries in distribution log Entry is on distribution queue Target N/A N/A N/A Source Active Waiting Message indicates file was sent Distribution log entries: *ORG - distribution originated *RTR - distribution routed *SND - distribution sent Entry is on distribution queue as "sending" Target Inactive Waiting No message indicates file was received Distribution log entries: *RCV - distribution received No confirmation message sent back to source Unable to WRKNETF/RCVNETF 
 
 Sending Files with SNADS
 
 Figure 2 The Work with Network Files Display
 
 UNABLE TO REPRODUCE GRAPHICS 
 
 Sending Files with SNADS
 
 Figure 3 Sending and Receiving with a Save File
 
 1. On the source system, use Create Save File (CRTSAVF) to create the save file. 2. Use the Save Object (SAVOBJ) or Save Library (SAVLIB) command to save objects to the save file. When you create a save file for SNDNETF, you can use only one SAVOBJ or SAVLIB per save file; you cannot run the commands multiple times to add to the save file. 3. Use the SNDNETF command to send the save file to another system. 4. On the target system, create a save file with the same name as the save file on the source system. 5. Use the RCVNETF command or WRKNETF option 1 to receive the network save file into the target system save file. 6. Use the Restore Object (RSTOBJ) or Restore Library (RSTLIB) command to restore objects from the target system save file to libraries on the target system. 7. Use the Delete File (DLTF) command to delete the save files on both systems. 
 
 Sending Files with SNADS
 
 Figure 4 The Display Distribution Services Log Panel
 
 UNABLE TO REPRODUCE GRAPHICS