Editor’s Note: This article is the third installment in a series exploring ways you can utilize the AS/400 Integrated File System (AS/400 IFS) to provide additional capabilities for your AS/400-centric network. See the September/October and November/December 1998 issues of Client Access/400 Expert for parts 1 and 2 of the series, respectively.
If you have attended an AS/400 Integrated File System (AS/400 IFS) presentation lately, you know that the AS/400 can store and serve many types of data files such as optical files, stream files, files served via networked PCs or Intel-based PC Servers (including files from Windows NT and Novell NetWare servers), files from UNIX workstations, and, of course, DB2/400 database files.
Most of these data types are stream file data. The AS/400 IFS provides and integrates access to these files. A stream file has no inherent structure, e.g., fields or records; a stream file is only a continuous stream of bytes. Certain special characters can be used to stand for end-of-line and end-of-file markers, and a character (often a comma) can be used to divide data into fields. However, this formatting is not inherent to the file; it must be inserted and managed by an application program.
In contrast, a DB2/400 database file has a built-in structure that consists of fields and records. DB2/400 files are found in the QSYS.LIB file system of the AS/400 IFS. AS/400 IFS commands and APIs provide access to all types of stream files stored in the AS/400 IFS as well as some files in the QSYS.LIB file system. The files in QSYS.LIB that can be accessed by AS/400 IFS commands and APIs include user spaces (.USRSPC), source physical file members, and program-described file members (.MBR). AS/400 IFS commands and APIs do not provide access to other DB2/400 files like programs (.PGM) or externally described (or DDS-described) database file members because these files are very different from a stream file and their structures can vary.
Think of stream files and DB2/400 file members as if they were system apples and oranges; they do not mix well and cannot be substituted for each other. A general rule of thumb is to continue to use the commands, APIs, and other interfaces that are designed to
manage DB2/400 database files while using the new AS/400 IFS commands and APIs to access stream files.
However, sometimes you need to copy your DB2/400 database file data into a stream file format or vice versa. For example, what if the data in a daily report database file needs to be served to PCs in the network for viewing in a spreadsheet? What if an application that is already written using APIs that operate on stream files also needs to access data stored in a database file? How do you perform these functions?
Using APIs to Move Data
One way to get data where you need it is to write an application program that uses traditional database interfaces to read data from the database file, and then use AS/400 IFS APIs to write the data to a stream file. The set of AS/400 IFS APIs open(), read(), write(), and close() is a good place to begin with for application development. For more information on using AS/400 IFS APIs, see Chapter 2 in AS/400 System API Reference (SC41-5801). This solution works well when DB2/400 files need to be moved on a regular basis. However, when the database file is complex, the stream file format is complex, or a move is infrequent, writing one of these programs can be a chore. In such cases, it’s easier to use OS/400 green-screen commands to move the data.
Using Commands to Move Data
There are two pairs of green-screen commands that, when used together, can help you move DB2/400 data to and from stream files. Copy to Stream File (CPYTOSTMF) and Copy from Stream File (CPYFRMSTMF) allow you to copy data from source physical files and program-described files to stream files. Along with copying the data, this pair of commands allows you to perform data conversion and insert or detect end-of-line characters. Data conversion is especially useful if the data is being served to PCs. PCs commonly expect data in ASCII format where DB2/400 database files are commonly stored in EBCDIC format.
The following example copies a database file to a stream file. The data is converted from CCSID 37 (EBCDIC English) to code page 850 (PC ASCII English). A line feed (*LF) character is inserted at the end of each database record as it is copied to the stream file.
payroll.file/may.mbr’) + TOSTMF(‘/home/payroll/
The following command copies the data back again. You convert from code page 850 by specifying *STMF in the Stream File Code Page (STMFCODPAG) parameter. This specification tells the command to convert the file from the code page format that it is currently tagged with. One database record is created from data found between each line feed (*LF) character in the stream file.
However, CPYTOSTMF and CPYFRMSTMF will not allow you to move data from complex, externally described (DDS-described) database files. A pair of newer commands provide that function: Copy to Import File (CPYTOIMPF) and Copy from
Import File (CPYFRMIMPF). The term import file refers to the stream type file. An import file is typically created for copying data between heterogenous databases. These import file commands are available in V4R3. Prior to that, they are available in some releases via PTF. When copying from a stream (or import) file, CPYFRMIMPF allows you to specify a field definition file, which describes the data in the incoming stream file. You can also specify that the stream file is delimited and which characters are used to mark string, field, and record boundaries. Options for converting special data types such as time and date are also provided. Data conversion is provided on these commands if the target stream file or database member already exists. If the file does not exist, you can use the following method to get the data converted:
1. Use the CPYTOIMPF/CPYFRMIMPF commands to copy the data between the externally described file and a source physical file.
2. Use the CPYTOSTMF/CPYFRMSTMF commands (which provide full data conversion regardless of whether the target file exists) to copy data between the source physical file created in step 1 and the stream file.
Here is an example of how you would copy the data to a source physical file:
CPYTOIMPF FROMFILE(DB2FILE)+ TOFILE(EXPFILE) DTAFMT(*DLM)+
STRDLM(‘“‘) DATFMT(*USA)+ TIMFMT(*USA)
The data format (DTAFMT) parameter specifies that the input stream (import) file is delimited. The other choice is DTAFMT(*FIXED), which requires a field definition file to be specified. The field delimiter (FLDDLM), record delimiter (RCDDLM), and string delimiter (STRDLM) parameters identify the characters that act as the delimiters—or separators—for the fields, records, and strings. The date format (DATFMT) and time format (TIMFMT) parameters indicate the format for any date and time information that is copied to the import file.
The commands are useful because they can be placed into a program and then run entirely on the AS/400. However, the interfaces of the commands are complex, but the Client Access tools that are described next are graphical, which makes them more user- friendly.
Using Express Client Tools to Move Data
To move data between AS/400 DB2/400 database files and AS/400 file system stream files, you can use the Data Transfer applications (Data Transfer To AS/400 and Data Transfer From AS/400) provided by IBM’s AS/400 Client Access Express for Windows (Express client). The Express client runs on Windows 95, Windows 98, and Windows NT. To transfer a file to or from a stream file on the AS/400, you must first establish a connection to the AS/400 and map a network drive to the appropriate path in the AS/400 file system.
To map a network drive for Client Access Express, you must use AS/400 Support for Windows Network Neighborhood (AS/400 NetServer) and perform two steps. First, you have to share the directory or folder from the AS/400. The administrator can create a new file share by right-clicking and choosing Sharing on the desired directory under the File Systems icon in the Operations Navigator tree for the AS/400. Make sure your mark the NetServer file share as read/write or the user will not be able to perform data transfer downloads or uploads. For more information about setting up your Windows desktop and your AS/400 for NetServer, see the IBM AS/400 NetServer Home page at www.as400.ibm.com/netserver.
Once the directory is shared and your PC Windows desktop is configured for AS/400 NetServer access, a network drive can be mapped by choosing the Map Network Drive option from the Tools pull-down menu in Windows Explorer. Use your AS/400 NetServer name and the file share name to map the drive, e.g., QMYAS400SharedDirectory.
To transfer data from a DB2/400 file to a stream file on your AS/400, use the Data Transfer from AS/400 icon in the Client Access Express folder. Selecting the icon will bring up the screen shown in Figure 1. In the AS/400 section of the screen, select the AS/400 system and the DB2/400 file names of the files you want to copy. You can type in the file name by using the QSYS.LIB library and file name, e.g., JOHN/FILE1(MBR1), or you can browse the available AS/400 libraries and files by clicking on the Browse button.
For the stream file you’ll be saving your AS/400 data to, fill in the fields in the PC portion of the screen. Select File from the Output Device pull-down menu to save the stream file as a straight ASCII file. If you want to convert the DB2/400 file to HTML instead of ASCII, select Hyper Text Markup Language (HTML) from the Output Device pull-down menu. Use the network drive you just mapped to specify the AS/400 IFS folder and file name you want to save the stream file to. You can also use the File name field to save the file to a PC or network hard drive. A browse button is available if you want to browse your system folders for the right location.
Click on the Format Options button to get the screen shown in Figure 2. For the stream file, specify the date and time formats, decimals format, etc. If you have date and time fields in your DB2/400 file, it is very important to specify that the date and time formats on this screen are the same as the date and time formats used in your DB2/400 file. For example, if your file fields use International Standard Organizations (ISO) date and time formats, click on the pull-down date and time format boxes on this screen and select [ISO] International Standards Organization for your format options. If you don’t match your date and time formats, your transfer could fail with an SQL error.
You can also click on the Details button in the PC area of the Data Transfer from AS/400 screen (Figure 1) and choose a well-known PC file format for the downloaded data such as ASCII text, BIFF3, CSV, DIFF, Tab-delimited Text, or WK4. To run the transfer, click on the Transfer from AS/400 button and the DB2/400 file will be converted into a stream file in the AS/400, PC, or network folder you specified.
To transfer data from a stream file on your AS/400 to a DB2/400 file, you can use the Data Transfer To AS/400 application, which displays the screen shown in Figure 3. For the PC File Name, choose Browse for the network drive you assigned and choose a stream file from an AS/400 folder; you can also use a stream file located on the PC or network. For the AS/400 file to transfer the data to, choose the system where the externally described database file is located or will be created. Choose an existing externally described file, or you can allow the command to create a DB2/400 file for you, which requires a field reference file. Click on the Details button to display the AS/400 File Details screen (Figure
4), which allows you to specify the following transfer parameters:
• File name: This is an associated format description file (.FDF) that describes the format of your stream file
• Create AS/400 object: Choose whether to append the data to an existing member, replace the data in an existing member, create a new member in your DB2/400 file to hold the data, or create a new file and member on your target AS/400.
• Field reference file name: If you opt to have the transfer create a new file and member during the transfer (rather than by using the Create AS/400 Database File option described below), you must also specify a field reference file to model the size and fields of your new file on. You can use the Browse button to search your AS/400 to find a suitable file to model your new file on.
After this information is entered, click on OK to save your settings and return to the Transfer screen (Figure 3). Click on the Transfer data to AS/400 button to complete the transfer.
To create a DB2/400 file on your AS/400, select the Create AS/400 Database File from the Tools pull-down menu of the Data Transfer To AS/400 application. This tool will parse a given stream file to determine the number, type, and size of the fields required in the resulting DB2/400 file. The tool can then create the database file definition on the AS/400. If you are moving data to an existing definition on the AS/400, the Data Transfer
application requires the use of an associated FDF. An FDF describes the format of a stream file, and is created by the Data Transfer From AS/400 application when data is transferred from a database file to a stream file.
If you don’t have an .FDF file available to transfer stream file data to your AS/400, here’s how to quickly create a simple one: Create an externally described AS/400 DB2/400 database file with a format that matches your source stream file (i.e., number of fields, types of data).
Create one temporary data record within the database file. Use the Data Transfer From AS/400 program to create a stream file and its associated .FDF file from this database file. Now, you can use the Data Transfer To AS/400 program and specify this new .FDF file with the source stream file you want to transfer.
You can also perform this data movement in a batch job with the Client Access Data Transfer applications. Proceed as above, but, instead of choosing the Transfer data to AS/400 or Transfer Data from AS/400 buttons, select the File menu option and save the transfer request as a data transfer from an AS/400 (.DTF), AS/400 to PC data transfer
(.TTO) file, data transfer to AS/400 file (.DTT), or a PC to AS/400 file transfer (.TFR). In the Client Access directory, there are two executables that can be executed in batch from a command line: RTOPCB, which takes either a .DTF or a .TTO file as a parameter, and RFROMPCB, which takes either a .DTT or a .TFR file as a parameter. You may set either of these commands to run on a scheduled basis by using a scheduler application. (No scheduling applications are supplied by Client Access.) One example of using a scheduler to run a batch job is to use the System Agent Tool (a part of the Microsoft Plus Pack) to specify the program to run (e.g., RTOPCB MYFILE.TTO) and a time at which to run the program.
The Express client Data Transfer applications have the advantage of an easy-to- follow graphical interface and automatic numeric and character data conversion. However, Data Transfer requires the installation of the Express client product and the use of both PC and AS/400 resources.
Moving data between a DB2/400 file and an AS/400 IFS stream file is slightly tricky. You must know what the data you are starting with looks like and what you want the result to look like. There are many choices. However, moving data is often necessary and allows users to use their data more productively. Many types of data that are effectively stored and maintained in a DB2/400 database are more easily used, particularly by PC users, in an AS/400 IFS stream file format. With a few commands or Express client tools, data can be moved between the formats. Once set up, the movement can occur smoothly as often as needed.
AS/400 System API Reference (SC41-5801)
Figure 1: The Client Access Data Transfer From AS/400 program allows you to move DB2/400 data to a stream file that can be contained on your AS/400 or on a PC.
Figure 2: The Change Format Options screen allows you to specify some data formatting for the downloaded stream file data.
Figure 3: The Client Access Data Transfer to AS/400 program allows you to move stream file data to a DB2/400 file on your AS/400.
Figure 4: The AS/400 File Details screen allows you to specify PC to AS/400 data transfer parameters.