| Spooled File (FILE) | File name of the spooled file. |
| Name of the Output File (OUTPFILE) | When the command CVTSPLxxxx is used, the values specified in the OUTPFILE (To Stream File) parameter determine where the file will be placed and how the file will be named.
The following variables are possible for determining the output path/file name. | %TMP% | The path “/TMP“ will be used as the output path. | | %HOME% | The „home path“ (“/HOME/USERNAME“) of the current user, who is executing the job, will be sought. If the user has no “home path”, then an error message will appear that recommends the creation of a home path for the current user. | | %CURDIR% | Current directory. | | %SPLUSER% | Name of the spooled file’s user. | | %USRDTA% | USRDTA attribute of the spooled file. | | %SPLOUTQ% | Name of the output queue. | | %SPLFILENAME% | The name of the output file will be taken from the the name of the spooled file. | | %USER% | Name of the current user. | | %DATE% | Current Date DD.MM.YYYY. | | %YEAR% | Current year YYYY. | | %YEAR2% | Current year YY. | | %MONTH% | Current month MM. | | %MONTHNAME% | Name of the current month. | | %DAY% | Current day. | | %WEEKDAY% | Current weekday e.g. Friday. | | %TIME% | Current time HH:MM:SS. | | %TIMESTAMP% | Current time stamp YYYY-MM-DD-HH.MM.SS.MSMSMS | | %DEFAULTPATH% | This variable will be filled in with the default values from the default settings of the *SPOOL module. If this command is used to define a server task, the following substitute values can be used to define the name of the output file dynamically. | | %USRDTA% | This variable will be filled in with the user data attribute of the spooled file. | | %USRDFNDTA% | This variable will be filled in with the user defined data attribute of the spooled file. |
Possible Special Values: | *IFS-Path Name | A relative or and absolute IFS path name can be defined, which specifies the name of the file, which will be created, and the directory, in which it will be stored. The IFS is a combination of file systems, which is available from Sys-tem i. Depending on the chosen file system, the file can be stored locally on the hard drive of the Power Systems or on another system of the network, which can be a PC, another System i, or a Unix-Server. The use of the IFS will be explained in detail later. | | *EXITPGM | This value tells i-effect that the storage location will be specified later by an exit program, which will be called up during i-effect’s processing. |
| IFS Path Name Explanation | The IFS (Integrated File System) is a combination of file systems that the Power Systems can use to save and call up information. Depending on which system has been selected, files can be saved locally on the Power Systems or saved on another system of the network.
The file name specified with the OUTPFILE parameter tells i-effect the name of the file, which will be created. With the file name it is also explicitly or implicitly determined, into which file system and directory the file will be saved.The path consists of four elements: |
The Suffix | If a name is entered that ends with a period (.), which is followed by a string, a suffix has been entered. |
Windows and other operating systems can use this suffix to determine the file type. If a file ending in .prn is run, then this file will most likely be opened with Word. This makes it even more important that the correct suffix has been specified for the creation of files. If, for example, RTVSPLDTA is used to create a file, then a name will be entered, which ends with a suffix such as .prn, which is often used for printer data stream files. |
| File Name | The part of the path name that precedes the extension is the name of the file itself. i-effect 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 chosen file system. For example, the QDLS file system (shared folders) does not allow the file name to be longer than 8 characters plus an optional extension of 1-3 characters (old DOS-style 8.3 naming). File names in some file systems are not case insensitive, (e.g. root file system) while file names in other file systems are case-sensitive (e.g. QopenSys) |
| Directory Path | Optionally, a directory or a list of sub directories can be specified, in which the file will be saved. If a directory has been named e.g. “Sales“ with sub directories for every region and then for year and month, the path could look like this
CODE
sales/north/2010/nov
to specify that the directory, in which the file will be saved, is the sub directory November in the sub directory 2010 of the sub directory for the northern region in the directory sales. |
| File System | Optionally, a file system can be specified at the beginning of a path, to indicate which file system the path refers to. The following is a list of commonly used file system names that can be used at the beginning of a path name. Note: 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 Power Systems hierarchical file system. | | /QDLS | Document Library Services (shared folders) | | /QNTC | Windows NT Server file system. This file system provides access to data and files that are stored on a server running Windows NT 4.0 or higher. Although this includes access to the data on a Windows NT Server that is running on an IXA (Integrated xSeries Adapter, previously known as the Integrated Netfinity Server, Integrated PC Server SIOP), it is NOT restricted to the IXA. This file system can be used to read and write data directly to or from a separate Windows server in the network. | | /QOpenSys | A hierarchical file system compatible with UNIX and POSIX. Uses case-sensitive names. | | /QSYS.LIB | The Power Systems database. Although it is possible to save i-effect output in a database file member, this is not recommended, as the data is unlikely to be easily accessible there. |
|
| | The difference between an absolute and a relative path name is also important. An absolute path name is one, which explicitly defines the full location where the file is to be saved. For example, the path name:
CODE
/Sales/North/2005/Nov/new_business.prn
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. | | .prn | The file extension, which indicates the printer data stream file. |
However, if a forward slash (/) has not been entered at the beginning of a path name, Power Systems 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 the current directory is already set to “/sales” the path:
CODE
north/2010/nov/new_business.prn
(without the leading /) would be interpreted relative to ”/sales” and would refer to exactly the same location as the absolute path:
CODE
/sales/north/2010/nov/new_business.prn
The current job directory can be set with the CHGCURDIR or CD commands. Often, the current directory will be set automatically when logging in on the Power Systems using the HOMEDIR (home directory) attribute of the user profile.
Assuming the user profile has HOMEDIR equal to /home/john, indicating that the current directory should, at login, be set to the “john” subdirectory within the “home” directory of the root file system. Unless it has been changed with CHGCURDIR or CD or if a relative path name has been specified, the path will be interpreted relative to the current directory :/. home/john. For example, the relative path “reports” would be interpreted as a subdirectory called reports within /home/john.
Path names must be enclosed in single quotes (‘ „) in the OUTPFILE parameter if they contain forward slashes or other special characters.For example:
CODE
OUTPFILE(new_business.prn)
is acceptable to OS/400 without single quotes, but Power Systems will insist that:
CODE
OUTPFILE (‚/sales/north/2010/nov/new_business.prn‘)
is entered with single quotes around the path name. When prompting the command with F4, the Power Systems will enclose the path name in quotes automatically if this has not been done already.
Further information on IFS can be found at:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/ifs/rzaaxkickoff.htm |
| Selection of Storage Space | When deciding where to save i-effect 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 the file system perform? Is saving and retrieving data from the 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 inaccessible when saving data to it or retrieving data from it? | | Access | What choices are there regarding access to the data? How easy is it to retrieve data from the file system in use with an appropriate application? For example, how easy is it to open a file in a PC application? | | 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 | Do only authorized users have access to the documents? | | Scalability | Will problems occur when volume increases? |
|
| The following examines several IFS file systems that are most fitting in light of these criteria. |
| Root-File System | The root file system is, in many ways, the default IFS file system and probably where most i-effect users choose to store their output. An i-effect file will be saved in the root file system if a path name is entered in the OUTPFILE parameter, which does not explicitly, or implicitly, refer to any other file system.
Users can access files created on Power Systems in the root file system using Client Access network drives. For example, if they have their K: drive assigned to the Power Systems root file system, they could open a file called sales_report.pdf saved in a directory called sales by opening K:/sales/sales_report.prn in Word. | Simplicity | Excellent. It is the simplest and easiest to use. Long file names are supported. Not case-sensitive. | | Performance | Good. Writing data locally will limit the time taken to create the files. Speed of retrieval from a PC will depend on network and other factors such as the processor strength and system utilization of the Power Systems. | | Reliability | Excellent. Writing data locally means that file creation is not dependent on the availability of the network or another system | | Access | Good. Easy access from Windows using Client Access network drives. | | Management | Good. Files can be backed up with Power Systems. Can be managed from the Power Systems command line or from Windows using a Client Access network drive. | | Security | Excellent. Power Systems security applies. | | Scalability | Good. Can be scaled as desired. | | Comments | Recommended unless other factors dictate otherwise |
|
| QDLS-File System | The QDLS or shared folders file system implements a DOS style method of storing PC files and other documents on the System i’s 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 predate the availability of the IFS (OS/400 V3R1M0).
An i-effect file is saved in the QDLS file system if a path name is entered in the OUTPFILE parameter which starts with /QDLS or if a relative path name is used and the current directory path starts with /QDLS. Users can access files created on Power Systems in the QNTC file system using Client Access network drives. For example, if users have their K: drive assigned to the Power Systems root file system, they could open a file called sales_report.prn saved in a shared folder called SALES by opening K:/QDLS/SALES/sales_report.prn with Word or a similar program. | Simplicity | Good. It is familiar to long-standing users of S/38 and AS/400 applications. Not case-sensitive. It‘s naming is limited to DOS style 8.3 conventions. Long file names will cause errors | | Performance | Poor when 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 Client Access network drives. | | Management | Good. Files can be backed up on Power Systems. Can be managed from the Power Systems command line or from Windows using a Client Access network drive. | | Security | Excellent. Power Systems security applies. | | Scalability | Good. Can be scaled as desired. | | Comments | Use the root file system where possible. |
|
| QNTC-File System | The QNTC file system is the Power Systems implementation of Windows network neighborhood. It allows the user to write and read 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 OS/400 V5R2M0 or above is required to read and write files stored under Windows XP.
An i-effect file is saved in the QNTC file system by entering a path name with the
OUTPFILE parameter which starts in /QNTC or if a relative path name is used and the 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 directory.
It is required that a Windows server called “server1” is on the network.
On the 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 QNTC is configured and the security settings allow it, a file called november.prn can be saved in that subdirectory from the Power Systems by specifying the path name
CODE
/QNTC/server1/sales/2010/november.prn
The QNTC file system can be quite difficult to configure and manage, but once running, it can provide a very effective means of creating i-effect output directly on a Windows server in the network.
Please note: the job’s Power Systems user profile, which accesses the QNTC, must have a name and password, which are exactly the same as an authorized and recoginzed user ID in the Windows network.Further information about QNTC is available at:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/ifs/rzaaxqntcfs.htm
Once i-effect files have been saved on a Windows server in the network, users can then access files created with i-effect on that Windows server using Windows networking. | Simplicity | After the initial set up, access is very easy! | | Performance | Creating files across the network on the PC server may be slow. Retrieval of files once created should be very fast but will depend on server and network loads. | | Reliability | Creating files across the network on the PC server requires both the server and the network to be available at the same time. | | Access | It is easy to access from Windows using Windows networking. | | Management | Good. Data will need to be backed up on the Windows server. | | Security | Good. Windows security applies. | | Scalability | Very Good. Inexpensive PC disks can be used. | | Comments | If file storage on a Windows PC server is preferred over System i, this is an ideal solution if the initial setup issues can be overcome and it can be ensured that the PC server will be available to the Power Systems when it needs to create the files. |
|
| Typical Solutions | When implementing i-effect, it is important to make the right choices about where the created files will be saved and accessed.
The following are a few typical approaches that users have successfully implemented in the past: | Save the Files in the System i’s Root File System | This is a simple, easy, and reliable method.
To save an i-effect file in the root file system, specify a path in the OUTPFILE parameter that does not indicate another file system. If an absolute path name is used, it must start with a forward slash (/).
Files saved in the root file system can be opened with PC applications (Acrobat, Excel, Word, etc.) by using Client Access network drives to open the file just as if it were saved locally on a PC or on a Windows or UNIX server.
A small disadvantage to this approach is that the files take up space on the more expensive Power Systems disks rather than on the PC disks.
Further information regarding Power Systems configuration for the access of PCs using the Power Systems Client Access Network Drives can be found at: http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/rzaij/rzaijconnetas.htm
Further information regarding configuration of user PCs for Power Systems access using the Power Systems Access network drives can be found at: http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/rzaij/rzaijnetserverpc.htm | | Save the Files directly to a Windows server using QNTC | As explained above, the QNTC file system allows the user to write directly to a Windows server from the Power Systems.
Once QNTC is configured, i-effect can be used to create files on a suitable Windows server by specifying a path name starting /QNTC in the OUTPFILE parameter of the i-effect command being run.
Once the files are saved on the Windows server, any authorized user, who can connect to that server, can access them. |
|
| Job Name (JOBNAM) | The selection of spooled files can be limited to the current job or to a specific job. If a specific job should be chosen, enter the qualified job name here.
Possible Special Values: | * | Only considers spooled files of the current job. | | *ALL | All spooled files on the system will be considered. |
|
| User | Enter the name of the spooled file’s owner. | | Job Number | Enter the name of the job that created the spooled file. |
|
| Spooled File Number (SPLNBR) | Determines the number of the spooled file, which will be converted.
Possible Special Values: | *ONLY | Converts the only spooled file with this name. | | *LAST | Converts the last spooled file with this name. |
|
| PC File Option (STMFOPT) | Using the parameter STMFOPT for data stream file options, the action that CVTSPL takes can be chosen if the data stream file, which was entered in the OUTPFILE parameter, already exists. If the data stream file does not yet exist, this parameter cannot be used.
The Following Options are Possible: | *NONE | If the file specified in OUPFILE parameter already exists, the existing file will not be changed, and the command will register an error. For security reasons this is the default setting. | | *UNIQUE | CVTSPL creates a file name for the output file(s) by adding a numerical suffix to the name entered in the OUTPFILE parameter (before the extension). This numerical suffix will be one higher than the last highest suffix of the file with the same name in the directory. | | *REPLACE | Replaces the existing file. | | *ADD | Adds the contents of the spooled file to the end of the existing data stream. This option can only be used in conjunction with TGTFMT (*TXT), (*XLS), or (*CSV). With version V1R3M0 it can also be used with *PDF with implementation of Merge-API and the MRGPDF command. In addition, for the creation of XLS files, *ADD was implemented. A worksheet of the existing file will be added to an already existing file. | | *EXITPGM | This option informs i-effect that the options of the data stream file will be defined when an exit program is run. The exit program must create an option structure of the CS_STM01 type. |
|
| Title of PDF Files (TITLE) | TITLE creates a title for the report. This title appears in Acrobat Reader by choosing “File” and “Document Info and General” from the menu.
Possible Special Values: | *NONE | The report has no title. (Default) | | *STMFILE | The title of the report is the same as the data stream file, which was entered in the OUTPFILE parameter. | | Report-title | The title that the report should have. |
|
| Page Size (PAGESIZE) | PAGESIZE defines the size of the page, in which the PDF file should be displayed or printed with Adobe Acrobat.
This parameter contains 2 elements: The following special values are possible for the main parameter: | *CALC | Country (Default) | i-effect chooses paper size based on the country code of the current job. Letter will be chosen if the country code is US (USA) or CA (Canada); for others A4 will be chosen. | | *SPLF | as the spooled file | CVTSPL will reproduce the dimensions of the original spooled file. These normally correspond to the page width and length specified on the CRTPRTF command when the printer file was created. In case of an AFP or IPDS spooled file containing several different page sizes or orientations, these will all be reflected on the corresponding pages of the PDF or RTF document. | | *DEVD | Default Printer | i-effect takes the page size from the attributes of the printer, which was specified in the PRTDEV parameter. | | *CUSTOM | Optional | The exact page size will be specified in the CUS-TOMPAGE parameter. This option is useful for paper sizes, which are not in the default options. |
Page orientation must be set in conjunction with each page size in the second element of this parameter!
| Paper Format | This element determines the paper format that i-effect uses when creating an output file.
Possible Values: | *A3 | 420 x 297 mm | | *A4 | 297 x 210 mm | | *A5 | 210 x 148 mm | | *B4 | 364 x 257 mm | | *B5 | 257 x 182 mm | | *LEGAL | 14 x 8.5 in | | *LETTER | 11 x 8.5 in | | *EXEC | 10.5 x 7.25 in | | *LEDGER | 17 x 11 in |
| | Orientation | Determines the reproduction of page orientation in the data stream file.
Possible Special Values: | *LANDSCAPE | Horizontal orientation. | | *PORTRAIT | Vertical Orientation. |
|
|
| User Defined Page Size (CUSTOMPAGE) | This parameter will be displayed if *CUSTOM has been entered in the parameter PAGESIZE. This parameter allows the user to use a page size that differs from the norms used by PDF or RTF. The default is DIN A4.This parameter contains three elements: | Width | Choose a measured value between 0.001 and 999,999. The default is 210. | | Length | Choose a measured value between 0.001 and 999,999. The default is 297. | | Unit of Measurement | Choose a measured value between 0.001 and 999,999. Please note: The program does not fit the contents to the page size specified. | *MM | Millimeter (Default) | | *CM | Centimeter | | *INCH | Inch |
| | | | Printer (Output device) (PRTDEV) | Enter the name of a printer, from which the attributes will be used, if the spooled file attributes are set to *DEVD. | | Name of the Output Device | | *SYSVAL | The printer from the system value QPRTDEV will be used. | | Zeichen-Wert | Enter the name of the printer, which will be used. |
|
|
| Page Options (PAGEOPTION) | Determines a list of options regarding the presentation of data on the page.
Special Value: | *CALC | i-effect will calculate the best possible orientation and scaling based on the spooled file attributes. |
|
| This parameter contains 3 elements: | | Rotation of Page Elements | This element determines whether automatic rotation and/or Computer Output Reduction (COR) are applied, which simulates the effects of the PAGRTT (*AUTO), PAGRTT (*COR), or PAGRTT (*DEVD) attribute on certain printers. If the spooled file has the attribute PAGRTT (*AUTO), PAGRTT (*COR) or PAGRTT (*DEVD), automatic page rotation will occur when the spooled file is printed on a printer and the spooled file does not fit on the page in its standard orientation. For example, if the attributes of the spooled file indicate that it is 132 columns wide at 10 CPI and 66 lines long at 6 LPI (i.e. 13.2 inches by 11 inches), and it is printed to a printer which uses letter or A4 paper, the spooled file is too large to fit on the paper. The printer will automatically reduce the size of the spooled file data (COR) and rotate the spooled file data (auto-rotation) in order to make it fit the paper. Please note: The paper size and orientation specified in the PAGESIZE parameter are interpreted as the shape and format of the paper prior to rotation. For example, if the document prints on letter paper (11 x 8.5 inches), it should be specified PAGESIZE (*LETTER *PORTRAIT) even if the document prints in landscape mode, since the paper is physically printed in portrait mode and the document contents are rotated to fit on it. | *SPLF | i-effect will decide if auto rotation and/or COR should be used. | | *NO | Neither auto rotation nor COR will be used. | | *YES | Auto rotation will be used but COR won’t be. | | *COR | Auto rotation and COR will be used. |
The second and third elements of this parameter indicate the horizontal and vertical scaling to be applied to data in the spooled file to make it fit the page. If the page size is being changed from the size defined in the spooled file (e.g. to convert a 13.2 x 11 inch spooled file to a 11 x 8.5 inch page, suitable for printing on a PC printer), it may be necessary to scale the contents of the spooled file to get the best fit to the new page size and the best possible readability on screen.
| | Horizontal Scaling | | *NONE | No scaling will be used. | | *CALC | If the conditions for COR (Computer Output Reduction) are met, i-effect® will calculate an appropriate scaling based on the dimensions of the original spooled file, the new page size, and any margins requested. | | *FITPAGE | Irrespective of whether the conditions for COR (Computer Output Reduction) are met, i-effect will calculate a scaling factor, which will fit the spooled file contents to the paper size and orientation selected on the PAGESIZE parameter. | | 0.01-99.99 | Enter the horizontal scaling factor. |
| | Vertical Scaling | | *NONE | No scaling will be used. | | *CALC | If the conditions for COR (Computer Output Reduction) are met, i-effect will calculate an appropriate scaling based on the dimensions of the original spooled file, the new page size, and any margins requested. | | *FITPAGE | Irrespective of whether the conditions for COR (Computer Output Reduction) are met, i-effect will calculate a scaling factor which will fit the spooled file contents to the paper size and orientation selected on the PAGESIZE parameter. | | 0.01-99.99 | Enter the vertical scaling factor. |
|
|
| PDF Password (PASSWORD) | PASSWORD attaches a password to PDF files when they are created. The file is protected, even when incorrectly delivered. With this function, business documents can be protected on the company server.
PDF documents can receive a creator/owner password and a user password. This password is case-sensitive.
The creation of a creator/owner password guarantees the bearer complete access to the document. This password allows the user to change the document, print it, copy it, and to add comments.
The user password guarantees complete or limited access, depending on the user’s authorization, which is specified when the PDF file was created.
The following access rights can be given: | · Whether the document may be printed | | · Whether text in the document may be copied | | · Whether the document can be modified (requires Acrobat) | | · Whether notes can be added to the document (requires Acrobat) |
|
