FAQ: Coolspools & the IFS

Coolspools and the IFS: Where the output is created depends on what you specify on the TOSTMF parameter of the CVTSPLxxxx or CVTDBFxxxx command that you ran (or the conversion options from the WRKSPLFPDM command).

By default, CoolSpools outputs to your current directory in the IFS. However, you can tell CoolSpools to output to any location your system i gives you access to, not just directories on the system i’s own disks, but also other systems such as Windows and UNIX servers. You just need to choose what suits you best.

Normally you will want to access these stream files from a PC application such as Adobe Acrobat Viewer, Microsoft Excel or Microsoft Word. How you access CoolSpools output from your PC depends on a number of factors which we will consider shortly.

The TOSTMF parameter

When you run one of the CVTSPLxxxx or CVTDBFxxxx commands, you specify where you want the output to go and what you want it to be called on the TOSTMF (To Stream File) parameter.

There are 3 basic options:

• IFS path name You can define an absolute or relative IFS path specifying the name of the file to be created and the directory in which it will be placed. The IFS is a collection of file systems provided by your system i. Depending on which file system you select, your output may be stored locally on your system i’ disks or remotely on another system on your network, which could be a PC, another system i a UNIX server etc. Use of the IFS is explained more fully below. The special value *FROMFILE (the parameter default value) tells CoolSpools to create a file name from the name of the input file and an appropriate extension based on the format of the file being created (e.g. .pdf for a PDF file, .xls for an Excel file etc.) and place it in the current directory of the job.Your current directory is usually set to your home directory as defined by the HOMEDIR attribute of your user profile, but can be changed using the CHGCURDIR (Change Current Directory) command.
• *FTP This tells CoolSpools to send the output using FTP (File Transfer Protocol) to another system running an FTP server process. This could be another system i, a PC server, a UNIX machine etc.
• *EXITPGM (Spool Converter only) This indicates that you will specify the location at a later stage in an exit program that will be called while CoolSpools is running.

Folder Locations with WRKSPLFPDM

When the WRKSPLFPDM command is widely available to end-users who may not have technical expertise, then it is important to understand where files will be generated when they run conversions. The default parameters supplied with CoolSpools will cause a filename with no path to be used as the target document, resulting in the converted file being placed in the user’s current directory. By default the user’s current directory is their home directory with a path /home/username. If no such folder exists then the IBM i platform will use the root directory of the IFS as the current directory instead. This is unlikely to be acceptable, so it is important to ensure that /home/username directories exist on the IFS for each user who may be performing CoolSpools file conversions with WRKSPLFPDM.

An alternative approach would be to create a folder on the IFS for the purpose of receiving all CoolSpools conversions, and which will be shared across all users. Once the folder has been created on the IFS, you can use one of the following approaches to direct WRKSPLFPDM converted files there:

• Change the user startup program to run command CHGCURDIR, so that all users have a current directory other than the default /home/username path.
• From the CoolSpools Spool Admin menu access Work With Std Options and change the default parameters of conversion commands 10-29 so that TOSTMF() includes a path before the filename. For example, if a folder named /reports has been created as a repository for converted documents, then change the parameter from TOSTMF(‘&F_&N_&U_&J_&S.&X’) to TOSTMF(‘/reports/&F_&N_&U_&J_&S.&X’)

Understanding IFS path names

The IFS (Integrated File System) is a collection of file systems that your system i can use to store and retrieve information. Depending on which file system you choose to use, the data may be stored locally (on your system i’ own disks) or remotely (on another system in your network).

When you enter a path name on the TOSTMF parameter, you are telling CoolSpools the name of the file you wish to create. You will also be telling it, explicitly or implicitly, in which file system and directory to save that file.

The path consists of four elements:

• The Extension If you type a name that ends with a period (.) and then a sequence of characters, you have specified an extension. For example: .pdf, .xls, .rtf Windows and other operating systems may use this extension to determine what type of file you have created. For example, if you double-click in Windows on a file name ending in .pdf, it is likely that Windows will start or switch to Adobe Acrobat Reader and open the file. This makes it very important that you should choose an extension which is appropriate to the type of file you are creating. For example, if you are using CVTSPLPDF to create a PDF file, specify a file name ending in .pdf so Windows recognizes that the file should be opened with Adobe Acrobat Reader, but if you are using CVTSPLXLS to create an Excel file, choose a file name ending in .xls to ensure that Windows recognizes the file as an Excel spreadsheet.
• The File Name The part of the path name that precedes the extension is the name of the file itself. CoolSpools does not impose any restrictions other than the limit of 1,024 bytes for the entire path name. Please note, however, that the syntax and rules that apply to the name will be dependent on the file system you choose. For example, the QDLS file system (“shared folders”) does not allow the file name to be longer than 8 characters with an optional extension of 1-3 characters (old DOS-style 8.3 naming). Also note file names in some file systems are case-insensitive (e.g. root file system) while file names in other file systems are case-sensitive (e.g. QOpenSys).
• The Directory Path You can optionally specify a directory or list of sub-directories in which the file is to be saved. For example, if you have a directory called sales with subdirectories for each region, and then subdirectories for each year and month, you may need to specify a path such as:

  sales/north/2010/nov

  To indicate that the directory in which you wish to save you file is the November subdirectory within the 2010 subdirectory of the north region’s subdirectory within sales.

• The File System You can optionally specify a file system name at the beginning of the path to indicate to which file system the path refers. Here is a list of commonly used file system names that can be used at the beginning of a path name. Note that each begins with a / (forward slash) and that the root file system is indicated by a single forward slash alone:
  

  /	The “root” file system. This is the “default” system i hierarchical file system.
  /QDLS	Document Library Services (“shared folders”)
  /QNTC	Windows Server file system. This file system provides access to data and objects that are stored on a server running Windows. Although this includes access to the data on an IXA (Integrated xSeries Adapter, previously known as the Integrated Netfinity Server, Integrated PC Server or FSIOP), it is NOT restricted to the IXA. This file system can be used to directly read data from and write data to a separate Windows server on your network.
  /QOpenSys	A hierarchical file system compatible with UNIX and POSIX. Uses case-sensitive names.
  /QSYS.LIB	System i objects and libraries. Although it is possible to save CoolSpools output in a database file member, this is not recommended as the data is unlikely to be easily accessed there.

You should also understand the difference between an absolute path name and a relative path name.

An absolute path name is one which explicitly defines the full location at which a file is to be saved.

For example, the path name

/sales/north/2010/nov/new_business.pdf

is an absolute path name which specifies the full location of a file to be created and breaks down as follows:

/	The initial / indicates the root file system
sales	The name of the directory in the root file system
north	The name of a subdirectory within /sales
2010	The name of a subdirectory within /sales/north
nov	The name of a subdirectory within /sales/north/2010
new_business	The name of the file to be created
.pdf	The file extension, indicating an Adobe Acrobat file.

However, if you do not enter a forward slash (/) at the beginning of a path name, your system i will interpret this as a relative path name. Relative path names are interpreted relative to the current directory of the job (similar to the current directory in Windows or DOS).

For example, if your current directory is already set to /sales, the path

north/2010/nov/new_business.pdf

(note there is no leading /) would be interpreted relative to /sales and would refer to exactly the same location as the absolute path

/sales/north/2010/nov/new_business.pdf

The current directory of your job can be set with the CHGCURDIR or CD commands. Often, the current directory will be set automatically for you when you sign on to the system i based upon the HOMEDIR (home directory) attribute of your user profile.

Assume that your user profile has HOMEDIR = /home/john, indicating that when you sign on the current directory should be set to the john subdirectory within the home directory of the root file system. Unless you have changed this with CHGCURDIR or CD, if you specify a relative path name, the path will be interpreted relative to your current directory /home/john.

For example, the relative path

reports/sales.pdf

would be interpreted as referring to a file called sales.pdf in a subdirectory called reports within /home/john.

You will need to enclose path names in single quotes (‘) on the TOSTMF parameter if they contain forward slashes or other special characters.

For example:

TOSTMF(new_business.pdf)

is acceptable to OS/400 without single quotes, but your system i will insist that:

TOSTMF(‘/sales/north/2010/nov/new_business.pdf’)

is entered with single quotes around the path name. When prompting the command with F4, the system i will enclose the path name in quotes for you if you have not already done it.

Be careful when using relative path names. We recommend the use of absolute path names. If you use relative path names, you may get different results depending on the user who is running the command as current directories could differ from one job or user to another.

Choosing where to store your output

When it comes to deciding where to save your CoolSpools output, a number of factors need to be considered, for example:

• Simplicity How easy is it to save files to and retrieve files from a particular IFS file system? Are the naming rules for the file system complex or restrictive?
• Performance How well does that file system perform? Is saving and retrieving data from that file system quick and efficient or slow and laborious?
• Reliability Will the file system always be available or is there a chance that it might be unavailable for some reason at the time when you try to save data to it or retrieve data from it?
• Access What choices do you have with regards to accessing the data? How easy is it to retrieve data from the file system you choose to use using an appropriate application? For example, how easy is it to open a PDF file in Acrobat from a PC?
• Management How easy is it to perform management functions on the files in the file system, such as backup, archiving and purging of old documents?
• Security Can you ensure that only the right people have access to the documents?
• Scalability Will problems occur when volumes increase?

We will now consider the various IFS file systems you are most likely to want to use according to these criteria.

Root File System

The “root” file system is in many ways the “default” IFS file system and is probably where most CoolSpools users choose to store their output.

You save a CoolSpools file in the root file system if you enter a path name on the TOSTMF parameter which does not explicitly and implicitly refer to any other file system.

Users can access files created on your system i in the “root” file system using network drives. For example, if your users have their I: drive assigned to the system i root file system, they could open a file called sales_report.pdf saved in a directory called sales by opening i:/sales/sales_report.pdf in Adobe Acrobat.

Simplicity	Excellent	The simplest and easiest to use. Long file names are supported.Not case-sensitive.
Performance	Good	Writing data locally will keep down the time taken to create the files.Speed of retrieval from a PC will depend on your network and other factors such as the power and loading of your system i.
Reliability	Excellent	Writing data locally means that file creation is not dependent on the availability of the network or another system.
Access	Good	Easy to access from Windows using network drives.
Management	Good	Can be backed up with the system i.Can be managed from the system i command line or from Windows using a network drive.
Security	Excellent	System i security applies.
Scalability	Moderate	High cost of system i disks a possible issue.
Comments		Recommended unless other factors dictate otherwise.

QDLS File System

The QDLS or “shared folders” file system implements a DOS-style method of saving PC files and other documents on the system i own disks. It is really a legacy file system providing backwards compatibility for older applications written for the S/38 or versions of OS/400 that pre-date the availability of the IFS (OS/400 V3R1M0).

You save a CoolSpools file in the QDLS file system if you enter a path name on the TOSTMF parameter which starts /QDLS or if you use a relative path name and your current directory path starts /QDLS. Users can access files created on your system i in the QNTC file system using network drives. For example, if you users have their I: drive assigned to the system i root file system, they could open a file called REPORT.PDF saved in a shared folder called SALES by opening i:/QDLS/SALES/REPORT.PDF in Adobe Acrobat.

Simplicity	Good	Familiar to long-standing users of S/38 and AS/400 applications.Not case-sensitive. Naming limited to DOS-style 8.3 conventions so long file names will cause errors.
Performance	Poor	Slow compared to the “root” file system.
Reliability	Excellent	Writing data locally means that file creation is not dependent on the availability of the network or another system.
Access	Good	Easy to access from Windows using network drives.
Management	Good	Can be backed up with the system i. Can be managed from the system i command line or from Windows using a network drive.
Security	Excellent	System i security applies.
Scalability	Moderate	High cost of system i disks a possible issue.
Comments		Use the “root” file system instead.

QNTC File System

The QNTC file system is the system i implementation of Windows network neighborhood. It allows you to write to and read from files stored on a Windows server running NT 4.0 or above. This is not restricted to the IXA (Integrated xSeries Adapter, previously known as the Integrated Netfinity Server, Integrated PC Server or FSIOP.

Please note that you will need OS/400 V5R2M0 or above to read and write to files stored under Windows XP.

You save a CoolSpools file in the QNTC file system if you enter a path name on the TOSTMF parameter which starts /QNTC or if you use a relative path name and your current directory path starts /QNTC. The file system name /QNTC should be followed by the name of the server, then the name of the shared resource on that server (e.g. the shared directory name) and then the path within that shared directory.

Imagine you have a Windows server which is known to the network as server1. On that server there is a directory called sales which is shared under the name sales. Within that shared directory there is a subdirectory called 2010. If you have QNTC configured and your security settings allow it, you can save a file called november.pdf in that subdirectory from the system i by specifying the path name:

/QNTC/server1/sales/2010/november.pdf

The QNTC file system can be quite difficult to configure and manage, but once you have it running it can provide a very effective means of creating CoolSpools output directly on a Windows server in your network.

Please note in particular that the system i user profile of the job which accesses QNTC must be the same name and have the same password as a user id that Windows networking recognizes.

Further information on QNTC is at:

http://www-1.ibm.com/support/docview.wss?uid=nas1aea450153eebf8ff8625670f0072550f&rs=110

http://www.itjungle.com/fhg/fhg031704-story04.html

http://www.itjungle.com/mgo/mgo111903-story02.html

Once you have saved your files on a Windows server in your network, users can then access files created with CoolSpools on that Windows server using Windows networking. For example, if they have their F: drive assigned to a directory called sales on that server, they could access a file called sales_report.pdf in that directory simply by opening file F:/sales_report.pdf.

Simplicity	Moderate	Can be difficult to set up and manage.Once files are saved on the Windows server, access should be very simple.
Performance	Moderate-good	The speed of creating files and retrieving files across the network on the PC server is dependent on factors such as network and PC loadings and may be slow.Typically the time taken to create files will be greater than for the /root file system, but, once created, they will be quicker to access.
Reliability	Low-moderate	Creating files across the network on the PC server requires both the server and the network to be available at the time and can require careful management.
Access	Excellent	Easy to access from Windows using Windows networking.
Management	Good	Will need to be backed up and managed under Windows.
Security	Good	Windows security applies.
Scalability	Excellent	Low-cost PC disks can be used.
Comments		If you prefer to store your files on a Windows PC server rather than on the system i, this is an ideal solution if the initial setup issues can be overcome and you can ensure that the PC server will be available to the system i when it needs to create the files.

Typical Solutions

When implementing CoolSpools, it is important to make the right choices about where you will save the files you create and how you will access them.

Here are a few typical approaches that users have successfully implemented in the past.

• Save the files in the system i “root”This is a really simple, easy and reliable method.To save a file in the “root” file system, you just specify a path name starting with a forward slash / and without any special file system identifier (i.e. not /QDLS, /QNTC etc.)You can open files saved in the root file system from your PC applications (Acrobat, Excel, Word etc.) by using network drives to open the file just as you would a file saved locally on you PC or on a Windows or UNIX server.The only real downside of this approach is that the files occupy space on your system i disks, which can be expensive compared to PC disks.See the section on NetServer below for details of how to make files stored on your system i available for access from a PC using a network drive.
• Save the files directly to a Windows server using QNTCAs explained above, the QNTC file system allows you to write directly to a Windows server from your system i.Once QNTC is configured, you can use CoolSpools to create your files on a suitable Windows server by specifying a path name starting /QNTC on the TOSTMF parameter of the CoolSpools command you are running.Once your files are saved on your Windows server, they can be accessed by any authorized user who can connect to that server.
• Save the files directly to a Windows or UNIX server using FTPAs an alternative to using the QNTC file system, if your Windows server is running the FTP service, you can use the CoolSpools TOSTMF(*FTP) option to send the output to that server via FTP.Once your files are saved on your Windows server, they can be accessed by any authorized user who can connect to that server.This method can also be used to send the output to a UNIX server.
• EmailIn the past you may have produced a large number of system i spooled files which were printed then distributed them on paper through your internal or external mail.This process can be transformed into an automated, low-cost electronic service by creating PDFs, RTFs or Excel files from your spooled files rather than printing them on paper.If you have installed CoolSpools Email (CoolSpools product option 2), or if you have some other method of sending email from your system i, you can them distribute them electronically by email. The stream files could then be deleted once they had been emailed if they were no longer required.

NetServer

In order to access file stored on the system i from a PC network drive, you must have NetServer running on your system i and you must have created an appropriate NetServer file share.

NetServer can be managed from a PC using System i Navigator (part of System i Access). However, System i Navigator can be slow and heavy on resource usage, so many customers find our FREE NetServer Toolkit (CoolSpools Product Option 5) a simpler and more convenient way to administer NetServer.

A NetServer file share is very similar to a shared directory on a Windows server, in that it makes a system i IFS directory available to access on the network. Users can assign a network drive under Windows by specifying a directory path such as:

\\systemi_name\share_name

where “systemi_name” is the name of the system i as known to NetServer (usually the system name prefixed by a Q, but modifiable using Ops Nav or the NetServer Toolkit CHGNETSVRA (Change NetServer Attributes) command;

or

\\systemi_IP_address\share_name

where “systemi_IP_address” is the IP address of the system i

“share_name” in both cases is the name of the share you created

If using NetServer Toolkit, you can create a file share with the CRTFILSHR command.

Further information on IBM NetServer can be found on the IBM website here.

If you need help with any of the techniques described above, feel free to contact our support team.