Excel-erator Programmer`s Guide and Reference

Excel-erator Programmer`s Guide and Reference
Edition
Eleventh Edition (January 2017) This edition applies to the licensed program Excel‐erator (Program 2A55XL1), Version 2 Release 2 Modification 0, and to all subsequent releases and modifications until otherwise indicated in new editions. This revision makes all previous editions obsolete. Make sure you are using the proper edition for the level of the product. This manual is available as option 1 from the XLERATOR menu, in PDF format in directory /Gumbo/Proddata/2A55XL1/doc on your system, and on the web at www.gumbo.com © Copyright Gumbo Software, Inc. 2001, 2017. All Rights Reserved. ii
Contents
Edition ................................................. ii
Contents............................................. iii
Chapter 1 Introduction....................... 5
Whatʹs In This Chapter ......................................5
Excel‐erator Overview .......................................5
Excel‐erator Feature............................................5
Product Support Features..................................6
Excel‐eratorʹs TOOBJ() Parameter ....................7
Product Positioning ............................................8
Future Directions ................................................9
Manual Conventions ..........................................9
Chapter 2 Installation....................... 11
Whatʹs In This Chapter ....................................11
Installing Excel‐erator ......................................11
Verifying Excel‐erator Installation .................13
Library List Considerations.............................13
Release Considerations ....................................13
New Release Testing ........................................14
Deleting Excel‐erator........................................15
Additional Installation Information...............15
Technical Support .............................................15
Hot Site Installation ..........................................16
Permanent Authorization Codes ....................16
Chapter 3 Menu ................................ 21
Whatʹs In This Chapter ....................................21
Accessing Menu XLERATOR..........................21
XLERATOR Menu Options .............................21
Chapter 4 Set Up .............................. 23
Whatʹs In This Chapter ....................................23
Selecting A Quick Start Procedure .................23
Quick Start Mail Set Up ‐ Mailhub .................24
Quick Start Mail Set Up ‐ Direct Delivery .....25
Using The SMTP Set Up Command...............26
Using The Mailhub Set Up Command...........27
Manual Mail Set Up Steps ...............................27
Additional Mail Set Up Resources .................33
Chapter 5 Implementation ............... 35
Whatʹs In This Chapter ....................................35
Overview............................................................35
Changing Programs..........................................35
Manually Processing Files ...............................36
Accessing Integrated File System Files ..........36
Creating PDM Options For Excel‐erator .......39
Selecting Records With OPNQRYF................41
Format Codes In Headers And Footers .........41
Email Addresses ...............................................42
Adding Line Breaks to the Message...............44
Digitally Signing The Message .......................45
CL Coding Tip...................................................45
Changing Command Defaults ........................46
Chapter 6 Conversion ...................... 47
Whatʹs In This Chapter ....................................47
Overview............................................................47
*BIFF8 Conversion ............................................48
*CSVUTF8 Conversion.....................................49
*CSVUTF8M Conversion.................................50
*CSVRFC Conversion.......................................50
*CSVRFCQ Conversion....................................50
*XMLSS Conversion .........................................51
*OOXML Conversion .......................................51
*BIFF4 Conversion ............................................52
Chapter 7 Commands ...................... 55
Whatʹs In This Chapter ....................................55
Change Excel‐erator Authorization (CHGXL1AUT)..................................................56
Change Excel‐erator Default (CHGXL1DFT)58
Check Excel‐erator Authorization (CHKXL1AUT)..................................................59
Copy To Excel (CPYTOEXCEL)......................61
Display Mail Log (DSPMAILLOG) ................79
Restart/Purge Local Mail (INZLOCAL).........81
Ping SMTP Mail Server (PINGMAIL)............83
Retrieve Gumbo PTF (RTVGSIPTF) ...............85
Send File Excel (SNDFEXCEL)........................87
Verify Local SMTP (VFYLOCAL).................105
Verify Mailhub Server (VFYMAILHUB) .....106
Verify Mail Router (VFYROUTER) ..............108
Chapter 8 Trouble-Shooting.......... 111
Whatʹs In This Chapter ..................................111
General Trouble‐Shooting .............................111
Software Installation Problems .....................111
XLS File Problems...........................................112
General Mail Delivery Problems ..................113
MSF Specific Delivery Problems...................116
iii
SMTP Specific Delivery Problems ................116
Appendix A Process Descriptions 119
Whatʹs In This Appendix ...............................119
SMTP Verification Process.............................119
SMTP Set Up Process .....................................121
Mailhub Verification Process ........................122
Mailhub Set Up Process .................................124
Appendix B Notices ....................... 127
Copyrights .......................................................127
Appendix C License Agreement ... 128
iv
Chapter 1 Introduction
What's In This Chapter
This chapter introduces you to Excel‐erator. The chapter: 






Gives an overview of Excel‐erator. Describes the features of Excel‐erator. Describes product support features. Describes Excel‐eratorʹs TOOBJ() parameter. Describes Excel‐eratorʹs relationship to other products. Outlines future directions for the product. Describes conventions used in this manual. Excel-erator Overview
Excel‐erator is an IBM i based software utility that converts IBM i database files into spreadsheets. The resulting PC files are either placed into any directory in IBM iʹs Integrated File System or sent as an attachment to an email. With Excel‐erator you can make IBM i data available to your users in the form best suited to them. Excel-erator Feature
Excel‐erator converts database files into spreadsheets. Excel‐erator supports the following database files: 

Physical files Logical files with a single record format Excel‐erator generates the following spreadsheet types: *OOXML
*XMLSS
*BIFF
*CSV
Microsoftʹs OfficeOpen XML. Microsoftʹs Excel specific ʺXML Spreadsheet formatʺ. Microsoftʹs Binary Interchange File Format. Comma Separated Values (CSV). There are two commands that provide the conversion: 

Copy To Excel (CPYTOEXCEL) Send File Excel (SNDFEXCEL) The Copy To Excel (CPYTOEXCEL) command takes a database file and an Integrated File System object (PC file) name as input. The fileʹs contents are converted into a spreadsheet. The converted file is then placed in the requested Integrated File System object (PC file). The Send File Excel (SNDFEXCEL) command takes a database file and an email address as input. The fileʹs contents are converted into a spreadsheet. The converted file is then emailed to the requested recipient using IBM iʹs built‐in mail support. IBM i delivers the mail in the manner appropriate to the recipientʹs mail client. The spreadsheet arrives as a MIME attachment to an email message. When sending the email, you have a wide variety of options to tailor the delivered message to your specific needs. Addressing includes multiple recipients, copy recipients and blind copy recipients. Chapter 1 Introduction
5
Additionally, you can include multiple Reply‐to: addresses as well as specify the email address the message appears to come from. Delivery confirmation by read receipt can also be specified. Optionally, a digitally signature can be included with the email. Both commands can generate spreadsheets in Excel format or Comma Separated Values format. Where the format allow, the commands support: 












Multiple database files per spreadsheet Field selection and ordering Addition of title lines Selecting column headings from the fileʹs field names, aliases or column headings (or *NONE) Control over column heading format including alignment, borders background pattern, bolding, etc. Addition of print header and print footer Specification of page setup Freezing rows and columns Selection of font typeface Addition of comments to cells File sharing settings including password protection and encryption Control over the color palette included in the spreadsheet Data in any coded character set ID (CCSID) Commands to help you trouble shoot and, optionally, automatically configure IBM i to send mail are also included with Excel‐erator. The conversion process is described in detail in Chapter 6 Conversion. Product Support Features
GUMBO products include a range of standard features that make them easy to use, easy to manage, and easy to live with: 







6
Extensive manual, both online as menu option 1 and in PDF Context sensitive help for every command and parameter. Menu that provides organized access to the productʹs features. Products are packaged as licensed programs and participates in the full range of support provided by IBM i Licensed program installation, PTF management, etc. are handled with the same commands used to manage IBM® software. Unlike IBM® Licensed Programs, our products are packaged to allow multiple releases to be installed at the same time, which facilitates new release testing. Product PTFs are available on the web at www.gumbo.com or can be retrieved and installed in a single step using our Retrieve Gumbo PTF (RTVGSIPTF) command. Our products include a hot site friendly automatic authorization function that allows you to immediately move operations to any back up or fail over machine without contacting us for a license key or authorization code. We include a Check Excel‐erator Authorization (CHKXL1AUT) command that allows you to exercise the productʹs authorization algorithm and insure there are no authorization ʺsurprisesʺ. Excel-erator Programmer's Guide and Reference




An installation verification option is available on the menu. You can easily verify that the product is correctly installed. All (applicable) objects in our products are digitally signed allowing you to verify their integrity. Modifications that could jeopardize the security of your system are easily detected with IBM iʹs Check Object Integrity (CHKOBJITG) command. Our products are upward compatible with future releases of IBM i. You can install a new releases of IBM i without installing a new release from us. Our products are compatible with all IBM i security levels. We use only published interfaces. Excel-erator's TOOBJ() Parameter
The key to generating PC files when using Excel‐eratorʹs Copy To Excel (CPYTOEXCEL) command is the TOOBJ() parameter. The parameter specifies the name of the file in terms of IBM iʹs Integrated File System. An Object (stream file) is a path that specifies the name and location of the file in terms of IBM iʹs Integrated File System. Depending on the Integrated File System path specified, you can place the generated file in any file system known to IBM i including writing directly to Windows systems on the network, another IBM i system or NFS server. Run the Work with Object Links (WRKLNK) command to view the available directories and file systems. As an example, the generated file can be placed in a directory in IBM iʹs Open Systems file system (QOpenSys). To create file ʺabc.txtʺ in directory ʺMyDirectoryʺ in IBM iʹs QOpenSys, use the following TOOBJ() parameter: TOOBJ('/QOpenSys/MyDirectory/abc.txt')
The path you specify must follow the naming conventions of the file system involved. For example, QOpenSys supports case‐sensitive names and each component of the path can be up to 255 characters long. For complete details on file system name restrictions see the Integrated File System topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. For additional information, see the Accessing Integrated File System Files section of this manual. Note: We recommend that you not use the /QDLS file system, which is accessed using the WRKFLR command, unless you have a specific requirement for its features. Excel‐erator provides several special values that can used to construct dynamic object (stream file) names. When the special values are found, the associated data is blank trimmed and substituted into the path specified when it is processed. If the data associated with a special value is blank, ʹBLANKʹ is substituted. If the data associated with a special value contains characters not allowed in an object name, question marks (ʹ?ʹ) for example, the name will be invalid and the command will fail. The special values must be delimited by an underscore (ʹ_ʹ) a period (ʹ.ʹ) a slash (ʹ/ʹ or ʹ\ʹ) a dash (ʹ‐ʹ) or another special value (which starts with ʹ*ʹ). The transform related special values are: *TRNEXT
Transform dependent file extension CHAR(3) or CHAR(4).  XLS for *BIFF8 or *BIFF4.  csv for *CSVUTF8, *CSVUTF8M, *CSVRFC, or *CSVRFCQ  xml for *XMLSS.  xlsx for *OOXML. Chapter 1 Introduction
7
The member related special values are: *FILE
*FILELIB
*MBR
*TEXT
*MBRCDAT
*MBRCCYY
*MBRCYY
*MBRCMM
*MBRCDD
*MBRCTIM
*MBRGDAT
*MBRGCYY
*MBRGYY
*MBRGMM
*MBRGDD
*MBRGTIM
File name CHAR(10). Library containing the file CHAR(10). Member name CHAR(10). Member Text ʹdescriptionʹ CHAR(50). Date the member was created CHAR(7) CYYMMDD. CYY portion of *MBRCDAT CHAR(3). YY portion of *MBRCDAT CHAR(2). MM portion of *MBRCDAT CHAR(2). DD portion of *MBRCDAT CHAR(2). Time the member was created CHAR(6) HHMMSS. Date the member was changed CHAR(7) CYYMMDD. CYY portion of *MBRGDAT CHAR(3). YY portion of *MBRGDAT CHAR(2). MM portion of *MBRGDAT CHAR(2). DD portion of *MBRGDAT CHAR(2). Time the member was changed CHAR(6) HHMMSS. As an example, given a member name of ʺDETAILʺ which was last changed 13:15:00, the following TOOBJ() parameter: TOOBJ('/MyDirectory/*MBR.*MBRGTIM.xlsx')
Generates the path: TOOBJ('/MyDirectory/DETAIL.131500.xlsx')
Product Positioning
Gumbo Software, Inc. has several IBM i based products: Number
2A55SAM
2A55SM1
2A55XL1
2A55SM2
2A55DCR
2A55RDA
2A55RM1
Licensed Program
Spool‐a‐Matic ‐ Convert IBM i spooled files to PDF, RTF, HTML, etc. in the Integrated File System SpoolMail ‐ Email IBM i spooled files as PDF, RTF, HTML, etc. Excel‐erator ‐ Convert IBM i database files into spreadsheets in the Integrated File System or as email Gumbo Mail ‐ Send email from your applications Dicer ‐ Merge/sort/split/duplicate spooled files Report Designer ‐ Edit DDS, RPG and ILE/RPG print specifications Report Manager ‐ Automate report distribution, bursting and spooled file management There is some overlap between and unique function within the products. Choose the product or combination of products that provide the function you need: 8
Excel-erator Programmer's Guide and Reference
┌───────────────────────────┐
│Product
│
┌─────────────────────────────────────────┼───┬───┬───┬───┬───┬───┬───┤
│ Function
│SAM│SM1│XL1│SM2│DCR│RDA│RM1│
├─────────────────────────────────────────┼───┼───┼───┼───┼───┼───┼───+
│ Primary input to product
│SPL│SPL│DBF│IFS│SPL│SRC│SPL│
│ Primary output from product
│IFS│EML│I/E│EML│SPL│SRC│SPL│
├─────────────────────────────────────────┼───┼───┼───┼───┼───┼───┼───+
│ Monitor output queues for work
│YES│YES│ ─ │ ─ │ ─ │ ─ │YES│
│ Spooled file distribution
│ ─ │ ─ │ ─ │ ─ │ ─ │ ─ │YES│
│ Burst (split) spooled files
│YES│YES│ ─ │ ─ │YES│ ─ │YES│
│ Merge/sort/duplicate spooled files
│ ─ │ ─ │ ─ │ ─ │YES│ ─ │YES│
│YES│YES│ ─ │ ─ │ ─ │ ─ │YES│
│ Convert spool to TXT stream file
│ Convert spool to PDF/RTF/etc stream file│YES│YES│ ─ │ ─ │ ─ │ ─ │ ─ │
│ Convert DB file to spreadsheet
│ ─ │ ─ │YES│ ─ │ ─ │ ─ │ ─ │
│ Email stream file as attachment
│ ─ │YES│YES│YES│ ─ │ ─ │YES│
│ Write stream to Integrated File System │YES│ ─ │YES│ ─ │ ─ │ ─ │YES│
│ Set up IBM i SMTP and mailhub
│ ─ │YES│YES│YES│ ─ │ ─ │YES│
│ Edit DDS, RPG, ILE/RPG source code
│ ─ │ ─ │ ─ │ ─ │ ─ │YES│ ─ │
├─────────────────────────────────────────┴───┴───┴───┴───┴───┴───┴───┤
│ Where: DBF ═ Database file
│
EML ═ Email
│
│
│
IFS ═ Stream file in the Integrated File System
│
│
I/E ═ Both IFS and EML
│
│
SPL ═ Spooled file
│
│
SRC ═ Source code
│
└─────────────────────────────────────────────────────────────────────┘
Future Directions
Future releases of Excel‐erator will include enhanced functionality based on customer feedback. Additionally, enhancements may be added to an existing release by Program Temporary Fix (PTF). Candidate enhancements include: 

Support for conversion to OpenDocument Format (ODF) as described in ISO/IEC 26300:2006 Open Document Format for Office Applications (OpenDocument) v1.0. Support for conversion to Office Open XML (OOXML) as described in ISO/IEC 29500:2008. Contact GUMBO to suggest additional enhancements. Manual Conventions
A note on conventions used in this manual. In several places, instructions for entering commands are given. When the command is intended to be run from a PC command prompt, it is flagged by [PC]. When the command is intended to be run from an IBM i command line, it is flagged by [ i ], or is not flagged at all. [Enter] denotes the enter key. Chapter 1 Introduction
9
Chapter 2 Installation
What's In This Chapter
This chapter describes 









How to install Excel‐erator. How to verify that Excel‐erator is installed correctly. How to include the XLERATOR library in a jobʹs library list. How to determine release dependencies. How to test a new release while leaving the old in production. How to remove Excel‐erator from the system. How to find additional installation information. How to contact technical support. Hot site installation. Permanent Authorization Codes. Installing Excel-erator
Follow these instructions to install Excel‐erator V2R2M0 on IBM i using physical media or a virtual image: Prepare
If you are upgrading a previous release (if Excel‐erator is currently installed), perform these steps before installing the software: 1.
2.
Read the Enhancement Summary to determine if any changes affect your installation. Insure that the product is not in use, as the installation process must clear the productʹs library. This will fail if objects such as menus are in use. If the installation fails, the previous release will be restored. Install
Note: If you are installing from a save file downloaded as an executable zip (.exe), use the save file specific ʺreadme.htmʺ instructions included in the download. 1.
2.
Sign on to the system as the security officer (QSECOFR). Verify that your machine is at IBM i V7R2M0 or later by running: WRKLICINF
Note: If you are running a version of IBM i earlier than V7R2M0 you cannot install Excel‐erator V2R2M0 on your machine. You must install an earlier version of Excel‐erator or upgrade the operating system. 3.
Verify that user domain objects are allowed in the libraries XLERATOR and QSRV, by running: WRKSYSVAL
SYSVAL(QALWUSRDMN)
Chapter 2 Installation
11
Take option 5 to display the value. If the value is not *ALL, use option 2 to add libraries XLERATOR and QSRV to the list of libraries where user domain objects are allowed. Note: QSRV is required to correctly process PTFs when they are loaded and applied. 4.
Insure that IBM i will be able to verify the signatures that we apply to our productʹs objects by installing our Signing Certificate and Root CA Certificate using Digital Certificate Manager. Alternately, insure that signature verification will not prevent the restore operation by running: WRKSYSVAL SYSVAL(QVFYOBJRST)
Take option 5 to display the value. If the value is 3 or higher, use option 2 to temporarily change the value to 1. 5.
6.
Mount the physical media or virtual image on the appropriate device. Submit the Restore Licensed Program (RSTLICPGM) command to batch: RSTLICPGM
LICPGM(2A55XL1) DEV(device-name) LNG(2924)
Note: Where ʺdevice‐nameʺ is the device where the media or image was mounted and is usually OPT01. Note: During the restore operation, the system operator message queue may receive inquiry message CPA3DE4 ʺDirectory not registered. (C G)ʺ. Unless you are using a directory naming convention similar to ours (that is the directory specified in the CPA3DE4ʹs second level text is unrelated to our software), you can safely respond with a ʺGʺ to reestablish the relationship between the directory and the product. Typically the message will occur three or four times. Finish
When the RSTLICPGM command completes, library XLERATOR and directory ʹ/Gumbo/ProdData/2A55XL1ʹ contain the new software. To complete the installation: 1.
If you have an Authorization or Instructions letter with your permanent authorization code, enter the code now. Note: Excel‐erator automatically grants 30 days usage for new installs or 90 days usage for release upgrades. 2.
Retrieve the current cumulative Excel‐erator PTF package by running the following command: XLERATOR/RTVGSIPTF
Note: GUMBO recommends downloading the current cumulative PTF package after installing the software. 3.
4.
12
Visit our PTF page at www.gumbo.com and check the Additional IBM i PTF Information section for IBM PTFs you may need to install. You can access the Excel‐erator menu by running the following command: Excel-erator Programmer's Guide and Reference
GO
MENU(XLERATOR/XLERATOR)
Verifying Excel-erator Installation
You can verify that Excel‐erator has been correctly installed by running the Check Product Option (CHKPRDOPT) command: CHKPRDOPT PRDID(2A55XL1) RLS(V2R2M0) CHKSIG(*NONE)
Note: If you have installed our digital certificates, specify CHKSIG(*ALL) instead of CHKSIG(*NONE) and digital signatures will be checked. If the message ʹNo errors detected by CHKPRDOPT.ʹ is displayed on the bottom of your display when the command finishes, Excel‐erator is installed correctly. If the message is not displayed, check your job log messages or see the Recovery Procedures in the Software Installation Problems section of the Trouble‐Shooting chapter of this manual. Library List Considerations
Library XLERATOR must be in the library list of jobs using Excel‐erator commands, or the commands must be qualified with library XLERATOR. Depending on your installation and intended use, you can choose to: 



Add library XLERATOR to the system library list. This insures every job in the system has access to Excel‐erator commands. However, this introduces problems with installing new releases and is not recommended. Add library XLERATOR to the initial library list parameter of job descriptions controlling jobs that will use Excel‐erator commands. (recommended) Run an ADDLIBLE XLERATOR command in individual threads requiring Excel‐erator commands. Qualify the command names on each use: XLERATOR/CHGXL1DFT
Library XLERATOR will be temporarily added to the product portion of the current threadʹs library list. Determine the best method for your installation and perform any changes required. Release Considerations
Excel‐erator operates under IBM i V7R2M0 or higher. Releases occur on a different schedule than IBM releases. Once Excel‐erator is installed, the following considerations apply: 
A new release of IBM i may be installed without installing a new release of Excel‐erator. Excel‐erator uses only published or IBM sanctioned interfaces and is upward compatible with all releases of IBM i. The Excel‐erator authorization code does not change. 
A new release of Excel‐erator may be installed without installing a new release of IBM i. Chapter 2 Installation
13
Any change in the requirements for operating system release level will be noted in the documentation accompanying the Excel‐erator release. The new authorization code must be entered. 
A new release of Excel‐erator may be installed over any prior release of Excel‐erator. You can skip ʺmissedʺ releases. 
More than one release of Excel‐erator may be installed on a system at one time. By restoring Excel‐erator to a library other than XLERATOR, a new release can be installed for testing while the old release remains in production. Any release‐to‐release considerations that may apply will be noted in the documentation accompanying the new release. Additional operational considerations may apply. For more information on renaming a library during licensed program installation, see the Restore Licensed Program (RSTLICPGM) command and the New Release Testing section of this chapter. 
When a new release of Excel‐erator is installed in the same library as an old release the following processing is performed in order to preserve data and Excel‐erator authorization information: 1. The Excel‐erator library is saved to QGPL/XL1VxRyMz. Where VxRyMz is the old release. 2. Product objects that contain default settings and operational information are copied to library QTEMP. 3. The Excel‐erator library is cleared. 4. Excel‐erator is restored. 5. Default settings and operational information are copied back to the product objects. 6. All objects duplicated to QTEMP are deleted. 7. Save file QGPL/XL1VxRyMz is deleted. Note: GUMBO recommends making a backup of the old release before installing a new release of Excel‐erator. New Release Testing
Unlike IBM licensed programs, GUMBO licensed programs are packaged in a way that allows multiple release to be installed at the same time. This feature allows you to test a new release while the old release remains in production. The key to new release testing are the LIB() and CODHOMEDIR() parameters of IBM iʹs Restore License Program (RSTLICPGM) command which allow you to restore the product to a library name and directory different from those used during packaging. To test a new release, follow this procedure: 1.
2.
14
Review the Enhancement Summary for any release‐to‐release considerations that could affect your installation. Install the new release in library XL1V2R2M0 and directory ʹ/Gumbo/ProdData/2A55XL1V2R2M0ʹ: Excel-erator Programmer's Guide and Reference
RSTLICPGM
LICPGM(2A55XL1) DEV(device-name) LNG(2924)
LIB(XL1V2R2M0) REPLACERLS(*NO)
CODHOMEDIR('/Gumbo/ProdData/2A55XL1V2R2M0')
Where ʺdevice‐nameʺ is the device where the media or image was mounted. 3.
4.
Perform your new release testing. When testing is complete, you must delete the new release. DLTLICPGM
LICPGM(2A55XL1) RLS(V2R2M0) OPTION(*ALL)
Note: Do not delete nor rename libraries and directories to move the new release into production. Doing so will corrupt the license program information kept internally by IBM i. If this has already occurred, see the Software Installation Problems section of the Trouble‐Shooting chapter of this manual. 5.
Follow the installation instructions to place the new release into production. Deleting Excel-erator
Follow these instructions to remove Excel‐erator from IBM i: 1.
2.
Sign on to the system as the security officer (QSECOFR). Delete the Excel‐erator library by using the Delete Licensed Program (DLTLICPGM) command: DLTLICPGM
LICPGM(2A55XL1) OPTION(*ALL)
These instructions delete an otherwise healthy installation of Excel‐erator. If the installation has been damaged, follow the instructions for Installation Fails in the Software Installation Problems section of the Trouble‐Shooting chapter of this manual. Additional Installation Information
Additional detailed installation information and instructions can be found in IBM i and related software > PDF file... > Installing, upgrading, or deleting IBM i and related software SC41‐5120 topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. Technical Support
If you encounter a problem with Excel‐erator you should: 

Review the information in the Trouble Shooting chapter for a description of and solution to common problems. Load and apply the current cumulative PTF package for the software. You can obtain the current package by visiting the web site listed below. If the problem remains unresolved, contact support@gumbo.com. Chapter 2 Installation
15
Hot Site Installation
In the event of a catastrophic system failure, an otherwise properly licensed and authorized copy of our product may be copied to a backup or failover machine. The productʹs authorization algorithm will detect that the software is operating on a machine serial number different from the licensed and authorized serial number and automatically create and install a 30‐day temporary authorization code for the backup or failover machine. You do not need to contact Gumbo Software, Inc. in the event of an emergency. An otherwise properly licensed and authorized copy of this product may be transferred to a backup or failover machine for the purpose of testing your emergency recovery procedures and the productʹs automatic temporary authorization function. The correct sequence of steps is as follows: 1.
2.
3.
4.
5.
6.
Install the software and enter the permanent authorization code on your production machine. Save the software from your production machine using the Save Licensed Program (SAVLICPGM) command. This creates an authorized copy, save it with your backups. When restoring to the backup or failover machine you must first insure that any previous copies have been deleted. To delete a previous copy use the Delete Licensed Program (DLTLICPGM) command. Restore the authorized copy to the backup or failover machine using the Restore License Program (RSTLICPGM) command. Confirm that the authorized copy was correctly restored by running the Check Product Option (CHKPRDOPT) command. The first time the software is used on the backup or failover machine the productʹs authorization algorithm will create and install a temporary authorization code running for 30 days. This allows you install the authorized copy in advance of a disaster. Permanent Authorization Codes
When you purchase a product from us, or when we send you a new release of a product, you receive a permanent authorization code. Here we describe how to determine the information you must give us in order to receive a permanent authorization code and how to determine if the permanent authorization code you have received is correct for your installation. The overwhelming majority of licenses purchased from us are System Wide Licenses. The other possibility, a Partition Only License, is described at the end of this section. For a System Wide License, permanent authorization codes are specific to a Serial Number, a Processor Group, and our productʹs Release. For a Partition Only License, permanent authorization codes are specific to a Serial Number, a Partition ID Number, the partitionʹs Maximum Processor Capacity, and our productʹs Release. In all cases, our permanent authorization codes are specific to a release of our product. The release of IBM i never makes a difference. To determine the release of our product installed on IBM i, run: DSPPTF LICPGM(2A55XL1)
Where the possible LICPGM numbers are: Number
2A55SAM
2A55SM1
2A55XL1
16
Licensed Program
Spool‐a‐Matic ‐ Convert IBM i spooled files to PDF, RTF, HTML, etc. in the Integrated File System SpoolMail ‐ Email IBM i spooled files as PDF, RTF, HTML, etc. Excel‐erator ‐ Convert IBM i database files into spreadsheets in the Integrated File System or as email Excel-erator Programmer's Guide and Reference
2A55SM2
2A55DCR
2A55RDA
2A55RM1
Gumbo Mail ‐ Send email from your applications Dicer ‐ Merge/sort/split/duplicate spooled files Report Designer ‐ Edit DDS, RPG and ILE/RPG print specifications Report Manager ‐ Automate report distribution, bursting and spooled file management The 5th line of the panel shows the release you are running. It is V2R2M0 in this example. Display PTF Status
System:
Product ID . . . . . . . . . . . . . :
IPL source . . . . . . . . . . . . . :
Release . . . . . . . . . . . . . . . :
Type options, press Enter.
5=Display PTF details
6=Print cover letter
Opt
PTF
ID
GUMBO4
2A55XL1
##MACH#A
V2R2M0
8=Display cover letter
IPL
Action
Status
(No PTFs found.)
Bottom
F3=Exit
F11=Display alternate view
F17=Position to
F12=Cancel
Note: It is possible that more than one release of a product is installed. To check, press returned to the command line, only one release is installed. [Enter]
. If you are All of our permanent authorization codes are serial number dependent. For a System Wide License they are also Processor Group dependent. To determine your systemʹs serial number and processor group, run: WRKLICINF
Lines 3 and 4 of the resulting panel show the serial number and processor group of your system. Chapter 2 Installation
17
Work with License Information
04/06/10
System serial number . . . . . . . . . :
Processor group . . . . . . . . . . . :
1234567
P10
Type options, press Enter.
1=Add license key
2=Change
5=Display detail
8=Work with license users ...
Opt
Product
5761SS1
5761SS1
5761SS1
5761SS1
5761SS1
5761SS1
5761SS1
License
Term
V6R1M0
V6
V6R1M0
V6R1M0
V6R1M0
V6R1M0
V6R1M0
Feature
5050
5051
5103
5112
5113
5114
5116
GUMBO4
18:08:32
6=Print detail
Description
IBM i
IBM i
Media and Storage Extensions
PSF 1-45 IPM Printer Support
PSF 1-100 IPM Printer Support
PSF Any Speed Printer Support
HA Switchable Resources
More...
Parameters or command
===>
F3=Exit
F5=Refresh
F11=Display Usage Information
F17=Position to
F23=More options
(C) COPYRIGHT IBM CORP. 1980, 2007.
F12=Cancel
For a Partition Only License, permanent authorization codes depend on the Partition ID Number and maximum processor capacity. How you determine the number and processor capacity of partitions on your system depends on whether or not you use HMC (Hardware Management Console) or SST (System Service Tools) to manage your hardware. If you use HMC (Hardware Management Console): 1.
2.
Go to Systems Management: Partitions task > Partition Properties > Hardware > Processors. Read the Processing Units, Maximum: value. If you use SST (System Service Tools): 1.
Start system service tools by running: STRSST
2.
3.
4.
5.
18
After entering a Service tools user ID and Service tools password, select the option to Work with system partitions. Select the option to Display partition information. Select the option to Display partition processing configuration. Note the Partition ID Number and Total Processor Maximum. Excel-erator Programmer's Guide and Reference
Display Partition Processing Configuration
System:
Number of system processors . . . . . . . . . . . : 2
Number of available system processors . . . . . . : 0
Size of system main storage (MB) . . . . . . . . : 4096
Size of available system main storage (MB) . . . : 0
Interactive feature available . . . . . . . . . . : 0
%
Partition
Identifier
0
1
GUMBO4
----------Total Processors---------Name
Current / Pending Minimum / Maximum
PRIMARY
1 /
1
1 /
1
SECONDARY
1 /
1
1 /
1
F3=Exit
F5=Refresh
F6=Print
F11=Display allocated I/O resources
F10=Main storage
F12=Cancel
Note: A Partition only license is not valid for a machine with only one partition. Note: Our productʹs algorithm checks the authorization against the Total Processors Current (aka. Assigned) value. If the maximum configured is larger than the license, the algorithm will grant usage as long as the current configured is within the licenseʹs limit, and will issue a warning. Chapter 2 Installation
19
Chapter 3 Menu
What's In This Chapter
This chapter describes how to access the Excel‐erator menu, and reviews the functions that can be performed from the menu. Accessing Menu XLERATOR
The Excel‐erator commands and functions that you will use most often are collected on menu XLERATOR. To access the menu use the Go To Menu (GO) command: GO
MENU(XLERATOR/XLERATOR)
Library XLERATOR is added to the product portion of the current threadʹs library list while the menu is displayed. XLERATOR Menu Options
XLERATOR
Excel-erator
System:
XL1
Select one of the following:
1. Reference Manual
Excel-erator
2. Copy To Excel
3 Send File Excel
4. Verify the product is installed correctly
Other
60.
61.
62.
63.
64.
65.
Options
Mail Verification And Set Up
Display Current PTF Status
Change Excel-erator Authorization
Search Help Index
Change Excel-erator Default
Check Excel-erator Authorization
CPYTOEXCEL
SNDFEXCEL
CHKPRDOPT
MAILSETUP
DSPPTF
CHGXL1AUT
STRSCHIDX
CHGXL1DFT
CHKXL1AUT
More...
Selection or command
===>
F3=Exit
F4=Prompt
F9=Retrieve
F12=Cancel
© Copyright Gumbo Software, Inc. 2001, 2017. All Rights Reserved.
Option 1. Reference Manual
Provides access to the Excel‐erator Programmerʹs Guide and Reference Manual. Option 2. Copy To Excel
The Copy To Excel (CPYTOEXCEL) command converts one or more IBM i database files into an Excel spreadsheet which is stored in IBM iʹs Integrated File System. Option 3. Send File Excel
The Send File Excel (SNDFEXCEL) command converts one or more IBM i database files into Excel spreadsheets which are then sent as an email to recipients. Chapter 3 Menu
21
Option 4. Verify the product is installed correctly
Installation verification checks to make sure that Excel‐erator has been correctly installed by running IBM iʹs Check Product Option (CHKPRDOPT) command. Option 60. Mail Verification And Set Up Menu
The Mail Verification And Set Up menu provides commands to help you set up mail on your system and verify that it is operating correctly. Option 61. Display Current PTF Status
Displays the Excel‐erator PTFs that have been applied to the software. Option 62. Change Excel-erator Authorization
The Change Excel‐erator Authorization (CHGXL1AUT) command changes the authorization code for Excel‐erator. The command is used to extend a demonstration period or to permanently authorize Excel‐
erator for a system or a partition. Option 63. Search Help Index
Search help index allows you to access the Excel‐erator help index and search for specific information. Option 64. Change Excel-erator Default
The Change Excel‐erator Default (CHGXL1DFT) command changes values used by Excel‐erator to control processing and other activities. Option 65. Check Excel-erator Authorization
The Check Excel‐erator Authorization (CHKXL1AUT) command executes Excel‐eratorʹs authorization verification function. This allows you to determine whether and how the product is authorized for use. Option 66. Retrieve Gumbo PTF
The Retrieve Gumbo PTF (RTVGSIPTF) command checks a remote system for new product PTFs, and, if available, downloads and installs them. 22
Excel-erator Programmer's Guide and Reference
Chapter 4 Set Up
What's In This Chapter
This chapter provides information on setting up IBM i to send email created by Excel‐erator. If you do not intend to use Excel‐erator to create email, you can skip this chapter entirely. The chapter describes: 






How to select a quick start mail set up procedure. Quick start mail set up ‐ Mailhub. Quick start mail set up ‐ Direct Delivery. How to use the Verify Local SMTP (VFYLOCAL) command. How to use the Verify Mailhub Server (VFYMAILHUB) command. Manual mail set up steps Additional mail set up resources. Selecting A Quick Start Procedure
Excel‐erator creates email by constructing a MIME formatted message and passing it to IBM i for processing and delivery. If IBM i is already configured for email delivery, no additional set up is needed and you can skip this chapter. If Excel‐erator is the first application on IBM i to generate email for delivery, there are IBM i configuration changes you must perform. Excel‐erator includes a Mail Verification And Set Up menu (GO XLERATOR/MAILSETUP) that provides tools to help you make them. However, the scope of this chapter is limited. If any of the following apply to your installation, proceed directly to the Additional Mail Set Up Resources section for references to help in configuring IBM i: 


Domino for IBM i is installed on the system. Multiple TCP/IP interfaces (other than *LOOPBACK) are configured. Multiple email domains require support. There are two quick start mail set up procedures for configuring IBM i mail services described in this chapter. The procedures are: 

Quick start mail set up ‐ Mailhub Quick start mail set up ‐ Direct Delivery. You only perform, at most, one of these. To select the correct procedure consider the following simplified configurations: Chapter 4 Set Up
23
Figure: Mail Configurations
Local Mailhub
LAN : Internet
┌───────────┐
┌───────────┐ :
│ IBM i ├────>│ LAN
├──┼───────────────────>
│
│
│ mailhub │ :
└───────────┘
└─────┬─────┘ :
│
:
local v
:
O
:
O /|\ O
:
/|\ / \ /|\ :
/\
/\ :
recipients
:
O
O /|\ O
/|\ / \ /|\
/\
/\
recipients
Remote Mailhub
LAN : Internet
┌───────────┐
: ┌───────────┐
│ IBM i ├────────────────────┼─>│ ISP
├────>
│
│
: │ mailhub │
└───────────┘
: └───────────┘
:
O
O /|\ O
/|\ / \ /|\
/\
/\
recipients
Direct Delivery
LAN : Internet
┌───────────┐
:
│ IBM i ├────────────────────┼───────────────────>
│
│
:
└───────────┘
:
:
O
O /|\ O
/|\ / \ /|\
/\
/\
recipients
For most customers IBM i is attached to a local area network that also has a mail server attached to it. Typically, the mail server runs on a PC with Exchange, Domino, SendMail, or similar mail application installed. In addition, typically, this mail server should be responsible for delivering mail, and will server as the forwarding mailhub server for IBM i. If this is your situation, proceed to the Quick Start Mail Set Up ‐ Mailhub section. For some customers, the mail server belonging to their internet service provider (ISP) is used to deliver email. If this is your situation, proceed to the Quick Start Mail Set Up ‐ Mailhub section. If you do not have a mail server capable of serving as a mailhub, or do not have access to an ISPʹs server, you must configure IBM i to deliver email directly. Proceed to the Quick Start Mail Set Up ‐ Direct Delivery section. Quick Start Mail Set Up - Mailhub
To configure IBM i to use a forwarding mailhub server follow these steps. If any of the steps fail, move on to the detailed sections of this chapter. 1.
2.
3.
4.
5.
6.
7.
8.
9.
24
Install Excel‐erator on IBM i (see the Installation chapter for details). Display the main menu (GO XLERATOR/XLERATOR). Run the option to verify that Excel‐erator is installed correctly. Display the Mail Verification And Set Up menu. Run option 12 to set up IBM i. Determine the name and IP address of the mailhub. Run option 14 to set up the mailhub specifying its name and IP. Press F12 to return to the main menu. Send a test to yourself using your ʺrealʺ email address. Excel-erator Programmer's Guide and Reference
10. Check your email. If after a reasonable time no email arrives, perform the following additional steps. 1.
Add your ʺrealʺ email address to your directory entry by running (this example uses ʺrealʺ email address ʺbillg@acme.comʺ and the directory entry ʺMYUSER MYSYSTEMʺ): CHGDIRE USRID(MYUSER MYSYSTEM)
MSFSRVLVL(*SYSMS) PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'billg')
(SMTPDMN SMTP 'acme.com'))
Note: If you are still signed on as QSECOFR, start a second session and sign on with your regular user profile to perform the send. 2.
3.
Display the Mail Verification And Set Up menu. Run option 61 to restart/purge local mail on IBM i. Note: If IBM i is currently being used to generate email from another application, make sure the Clear SMTP during restart (SMTPPURGE) and Clear MSF during restart (MSFPURGE) parameters specify *NO to prevent email from being deleted. 4.
5.
Send a test to yourself taking by taking the default *CURRENT. Check your email. If after a reasonable time no email arrives, move on to the detailed sections of this chapter. For additional information, see the Trouble‐Shooting chapter of this manual. Quick Start Mail Set Up - Direct Delivery
If your installation does not include a mail server or if you do not have access to an ISPʹs mail server, you can configure IBM i to directly deliver email to the world at large using the following steps. If any of the steps fail, move on to the detailed sections of this chapter. 1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
Install Excel‐erator on IBM i (see the Installation chapter for details). Display the main menu (GO XLERATOR/XLERATOR). Run the option to verify that Excel‐erator is installed correctly. Display the Mail Verification And Set Up menu. Run option 12 to set up IBM i. Configure IBM i access to DNS (see Manual Mail Set Up Steps). Remove previously configured mailhub and mail router (see Manual Mail Set Up Steps). Update the public DNS records for your domain (see Manual Mail Set Up Steps). Press F12 to return to the main menu. Send a test to yourself using your ʺrealʺ email address. Check your email. If after a reasonable time no email arrives, perform the following additional steps. Chapter 4 Set Up
25
1.
Add your ʺrealʺ email address to your directory entry by running (this example uses ʺrealʺ email address ʺbillg@acme.comʺ and the directory entry ʺMYUSER MYSYSTEMʺ): CHGDIRE USRID(MYUSER MYSYSTEM)
MSFSRVLVL(*SYSMS) PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'billg')
(SMTPDMN SMTP 'acme.com'))
Note: If you are still signed on as QSECOFR, start a second session and sign on with your regular user profile to perform the send. 2.
3.
Display the Mail Verification And Set Up menu. Run option 61 to restart/purge local mail on IBM i. Note: If IBM i is currently being used to generate email from another application, make sure the Clear SMTP during restart (SMTPPURGE) and Clear MSF during restart (MSFPURGE) parameters specify *NO to prevent email from being deleted. 4.
5.
Send a test to yourself taking by taking the default *CURRENT. Check your email. If after a reasonable time no email arrives, move on to the detailed sections of this chapter. For additional information, see the Trouble‐Shooting chapter of this manual. Using The SMTP Set Up Command
The Verify Local SMTP (VFYLOCAL) command performs automatic verification and set up of SMTP on IBM i. The command accepts a single parameter that determines if changes are made to IBM i. To verify IBM i without making any changes select option 11 on the Mail Verification And Set Up menu or run the following command: VFYLOCAL SETUP(*NO)
To make changes to IBM i select option 12 on the Mail Verification And Set Up menu or run the following command: VFYLOCAL SETUP(*YES)
In both cases SMTP verification is performed. Only if SETUP(*YES) is specified does the command try to perform set up functions. You must be authorized to perform all of the verification and set up functions or the command fails. You can insure that you are authorized to perform all functions by signing on as QSECOFR. Note: If you prefer to manually perform the functions of this program see the Appendix for a detailed description. A log of activity is created during verification and set up. To view the log run DSPJOB, take option 4 and display the last spooled file. If errors were encountered, detailed information can be found in your joblog. To view the information generated by VFYLOCAL, run the following command after the command has completed: DSPJOBLOG
26
Excel-erator Programmer's Guide and Reference
When the joblog is displayed, press F10 to display detailed messages and F18 to position to the end of the log. The recommended procedure is to run verification first and review the results before running automatic set up. Using The Mailhub Set Up Command
The Verify Mailhub Server (VFYMAILHUB) command performs automatic verification and set up of a forwarding mailhub server for IBM i. The command accepts three parameters that determine if changes are made to IBM i and the identity of the mailhub. To verify the mailhub without making any changes select option 13 on the Mail Verification And Set Up menu or run the following command (substitute the name and IP address of your forwarding mailhub server for ʺhost_nameʺ and ʺipʺ): VFYMAILHUB RMTSYS(host_name) INTNETADR(ip) SETUP(*NO)
To make changes to IBM i select option 14 on the Mail Verification And Set Up menu or run the following command (substitute the name and IP address of your external mailhub for ʺhost_nameʺ and ʺipʺ): VFYMAILHUB RMTSYS(host_name) INTNETADR(ip) SETUP(*YES)
In both cases mailhub verification is performed. Only if SETUP(*YES) is specified does the command try to perform set up functions. You must be authorized to perform all of the verification and set up functions or the command fails. You can insure that you are authorized to perform all functions by signing on as QSECOFR. Note: If you prefer to manually perform the functions of this program see the Appendix for a detailed description. A log of activity is created during verification and set up. To view the log run DSPJOB, take option 4 and display the last spooled file. If errors were encountered, detailed information can be found in your joblog. To view the information generated by VFYMAILHUB, run the following command after the command has completed: DSPJOBLOG
When the joblog is displayed, press F10 to display detailed messages and F18 to position to the end of the log. The recommended procedure is to run verification first and review the results before running automatic set up. Manual Mail Set Up Steps
Depending on IBM iʹs, network configuration and your intended usage, there are several manual mail set up steps you may need to perform in order to use SMTP. These are described here. Installing TCP Connectivity Utilities
In order to send email from IBM i, SMTP support must be installed. SMTP functions are delivered free of charge with IBM i as part of a separately installed licensed program product: 57xx‐TC1 TCP/IP Connectivity Utilities. Detailed installation information and instructions can be found in IBM i and related software > PDF file... > Installing, upgrading, or deleting IBM i and related software SC41‐5120. Chapter 4 Set Up
27
Changing Local Host and Domain Names
SMTP uses IBM iʹs local host and domain name to identify itself to remote SMTP hosts to which it is sending mail. To configure the names: 


Run the Configure TCP/IP (CFGTCP) command. Select option 12 (Change TCP/IP domain information). Enter a host and domain name for IBM i. As an example, we use ofc.gumbo.com as the domain name and the mailout as the host name on our machine. If your domain is widget.com you might use: Change TCP/IP Domain (CHGTCPDMN)
Type choices, press Enter.
Host name
. . . . . . . . . . .
Domain name
. . . . . . . . . .
'mailout'
'ofc.widget.com'
Domain search list . . . . . . .
*DFT
Host name search priority . . .
Domain name server:
Internet address . . . . . . .
*LOCAL
F3=Exit
F4=Prompt
F5=Refresh
F13=How to use this display
F10=Additional parameters
F24=More keys
*REMOTE, *LOCAL, *SAME
'192.0.2.1'
'192.0.2.2'
Bottom
F12=Cancel
Creating a TCP Interface
A TCP interface establishes IBM iʹs identity (internet address) on a given line description. Typically, the line description for a local area network is used. In order to add a TCP interface to a line description, you must determine the IP address and subnet mask to use. If you have a network administrator or other person responsible for assigning internet (IP) addresses, contact them. If you will connect IBM i directly to the Internet, you must request that your internet service provider assign you an IP address or you must request that the Internet Corporation for Assigned Names and Numbers (ICANN) assign you a network number. If you will not connect IBM i directly to the internet, and otherwise do not have an IP address for your system, you can use IP address ʺ192.168.1.1ʺ and Subnet Mask ʺ255.255.255.0ʺ. This number is taken from the class B ʺ192.168.0.0ʺ network, which is reserved for internal networks as described in RFC1597. To add an interface after you have determined an IP address and subnet mask, run the following command: ADDTCPIFC
INTNETADR(192.168.1.1) +
LIND(line_description_name) +
SUBNETMASK(255.255.255.0)
Substitute your values for the three parameters. 28
Excel-erator Programmer's Guide and Reference
Adding Host Name To Host Table
In order to deliver email correctly IBM iʹs SMTP host name must be associated with an IP address of one its TCP interfaces. This can be accomplished through DNS or you can add a local host table entry. To add a host table entry for IP address ʺ192.168.1.1ʺ with host name mailout, run the following command: ADDTCPHTE
INTNETADR('192.168.1.1') +
HOSTNAME(('mailout'))
Substitute your values for the two parameters. If the IP address already exists in the host table, use Change TCP/IP Host Table Entry (CHGTCPHTE) command to add the additional host name to the IP address. Configuring IBM i Access To DNS
When not using a mailhub, IBM i must access domain name system (DNS) servers to determine how to deliver email for a recipient. Typically, IP addresses for DNS servers are supplied by your internet service provider (ISP) or network administrator. If neither is available, a reasonable guess as to the IPs to use can be retrieved from a PC attached to the local area network that contains IBM i: 

Choose Start > Programs > Accessories > Command Prompt [PC] Run command: [PC]
ipconfig /all

[Enter]
Note the IP addresses given for DNS Servers. [PC]
Host Name . . . . . . .
Primary Dns Suffix . .
Node Type . . . . . . .
IP Routing Enabled. . .
WINS Proxy Enabled. . .
DNS Suffix Search List.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
:
:
:
:
:
:
Connection-specific DNS Suffix
Description . . . . . . . . . .
Physical Address. . . . . . . .
Dhcp Enabled. . . . . . . . . .
Autoconfiguration Enabled . . .
IP Address. . . . . . . . . . .
Subnet Mask . . . . . . . . . .
Default Gateway . . . . . . . .
DHCP Server . . . . . . . . . .
DNS Servers . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
:
:
:
:
:
:
:
:
:
:
PC001
Unknown
No
No
ofc.widget.com
Ethernet adapter Widget Net:
ofc.widget.com
Broadcom 802.11b/g WLAN
00-11-22-33-44-55
Yes
Yes
192.0.2.10
255.255.255.192
192.0.2.1
192.0.2.132
192.0.2.1
192.0.2.2
Lease Obtained. . . . . . . . . . : Sunday, July 21, 2012 4:30:38 PM
Lease Expires . . . . . . . . . . : Monday, July 22, 2012 4:30:38 PM
C:\Documents and Settings\Programmer>
To configure IBM i to use DNS servers and confirm correct operation: 
From the IBM i command line, type CHGTCPDMN and press F4. Chapter 4 Set Up
29

Enter the DNS IP addresses in the Domain name server: Internet address (INTNETADR) parameter, press enter. Change TCP/IP Domain (CHGTCPDMN)
Type choices, press Enter.
Host name
. . . . . . . . . . .
Domain name
. . . . . . . . . .
'mailout'
'ofc.widget.com'
Domain search list . . . . . . .
*DFT
Host name search priority . . .
Domain name server:
Internet address . . . . . . .
*LOCAL
F3=Exit
F4=Prompt
F5=Refresh
F13=How to use this display
*REMOTE, *LOCAL, *SAME
'192.0.2.1'
'192.0.2.2'
F10=Additional parameters
F24=More keys
Bottom
F12=Cancel
This example uses the fictitious DNS IP addresses 192.0.2.1 and 192.0.2.2 
Run the command: ping ibm.com

If you do not get the message ʺUnknown host, ibm.comʺ DNS is working correctly. Note: You may or may not get ping replies, but that is not important. Removing Previously Configured Mailhub and Mail Router
IBM i will deliver email directly if a mailhub and mail router are not configured. To check or remove the mailhub and mail router specifications, prompt the Change SMTP Attributes (CHGSMTPA) command, page down once and change the Mail router (MAILROUTER) parameter to *NONE: 30
Excel-erator Programmer's Guide and Reference
Change SMTP Attributes (CHGSMTPA)
Type choices, press Enter.
User ID delimiter . . . . . . .
Mail router . . . . . . . . . .
'.'
*NONE
*SAME, *DFT, ?, =, ., &, $...
Coded character set identifier
Outgoing EBCDIC/ASCII table:
Outgoing EBCDIC/ASCII table
Library . . . . . . . . .
Incoming ASCII/EBCDIC table:
Incoming ASCII/EBCDIC table
Library . . . . . . . . .
Firewall . . . . . . . . . . .
Journal . . . . . . . . . . .
Process all mail through MSF .
Percent routing character . .
00819
1-65533, *SAME, *DFT
.
.
*CCSID
Name, *SAME, *CCSID, *DFT
Name, *LIBL, *CURLIB
.
.
.
.
.
.
*CCSID
Name, *SAME,
Name, *LIBL,
*SAME, *YES,
*SAME, *YES,
*SAME, *YES,
*SAME, *YES,
F3=Exit
F4=Prompt
F24=More keys
F5=Refresh
*YES
*YES
*YES
*YES
F12=Cancel
*CCSID, *DFT
*CURLIB
*NO
*NO
*NO
*NO
More...
F13=How to use this display
If you are running V5R4M0 skip this step. If you are running V6R1M0 or later, page down three more times and change the Forwarding mailhub server (FWDHUBSVR) parameter to *NONE: Change SMTP Attributes (CHGSMTPA)
Type choices, press Enter.
Override reject connect list
Allow bare line feed . . . .
Verify identification . . .
Allow authentication . . . .
Verify MSF messages . . . .
Verify from user . . . . . .
Forwarding mailhub server .
F3=Exit
F4=Prompt
F24=More keys
.
.
.
.
.
.
.
.
.
.
.
.
.
.
F5=Refresh
*NO
*YES
*NO
*NONE
*NO
*ALL
*NONE
F12=Cancel
*SAME,
*SAME,
*SAME,
*SAME,
*SAME,
*SAME,
*NO, *YES
*NO, *YES
*NO, *YES
*RELAY, *LCLRLY, *NONE
*YES, *NO
*ALL, *LIST, *NONE
Bottom
F13=How to use this display
Updating Public DNS Records
When directly delivering email to the world at large, IBM i contacts each recipientʹs mail server and introduces itself using the fully qualified SMTP host name configured using the Change TCP/IP Domain (CHGTCPDMN) command. In the example below, the machine introduces itself as mailout.ofc.widget.com. Chapter 4 Set Up
31
Change TCP/IP Domain (CHGTCPDMN)
Type choices, press Enter.
Host name
. . . . . . . . . . .
Domain name
. . . . . . . . . .
'mailout'
'ofc.widget.com'
Domain search list . . . . . . .
*DFT
Host name search priority . . .
Domain name server:
Internet address . . . . . . .
*LOCAL
F3=Exit
F4=Prompt
F5=Refresh
F13=How to use this display
F10=Additional parameters
F24=More keys
*REMOTE, *LOCAL, *SAME
'192.0.2.1'
'192.0.2.2'
Bottom
F12=Cancel
When a recipientʹs mail server is contacted by IBM i, the mail server sees the traffic as coming from the publicly visible IP address of your connection. For example, the external IP address of your DSL modem. To determine the IP address seen externally, go to http://network‐tools.com. The IP address shown in the search box is the external public IP address of your connection. Increasingly, mail servers are confirming the identity of machines sending email by performing a DNS look up on the fully qualified host name sent during the introduction, mailout.ofc.widget.com in this example. If the IP address returned by DNS is not the same as the visible IP address the traffic is coming from, email is rejected or discarded as spam. To insure that IBM i passes this test, you must add, or have your domain registrar add, an address record for IBM iʹs fully qualified SMTP host name to the DNS records for your domain. In this example: mailout.ofc.widget.com. IN A nnn.nnn.nnn.nnn
Is added to the DNS records for the domain widget.com where nnn.nnn.nnn.nnn is the publicly visible IP address determined above. This usually requires contacting your domain name registrar or the ISP hosting your domain, and is not an IBM i setting. Setting Up Local Users
A local user is someone who has a user profile (sign‐on) on IBM i. You should set up each local user who will be sending email to insure that the apparent ʺFrom:ʺ address in the email will be correct and to insure that replies reach the sender. You do not need to set up local users who will not be sending mail. To configure hypothetical user JOE SALES (user profile JOES) as joe@acme.com, perform the following: 
If Joe already has a directory entry run: CHGDIRE USRID(JOE SALES) MSFSRVLVL(*SYSMS)
PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'joe')
(SMTPDMN SMTP 'acme.com'))
32
Excel-erator Programmer's Guide and Reference

If Joe does not have a directory entry run: ADDDIRE USRID(JOE SALES) USRD('Sample entry')
USER(JOES) SYSNAME(*LCL)
MSFSRVLVL(*SYSMS) PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'joe')
(SMTPDMN SMTP 'acme.com'))
The user is now ready to send mail from IBM i as joe@acme.com. For more details or information on setting up remote users, see the Email Addresses section of the Implementation chapter of this manual. Changing The System Start Program
You may wish to check your systemʹs start up program to insure that the required subsystems are started automatically when IBM i IPLs. The following steps are recommended: 
Insure that the SMTP server starts automatically when the Start TCP/IP (STRTCP) command is run: CHGSMTPA AUTOSTART(*YES)

Insure that your system start up program starts TCP/IP by including the command: STRTCP

Insure that your system start up program starts the IBM i Mail Server by including the command: STRMSF
Changing The Time Zone System Value
The time stamp placed in the email is based on the QTIMZON system value. Since most IBM iʹs have the correct time, an incorrect time stamp usually indicates an incorrect time zone setting. For information on correctly setting the QTIMZON system value see the System management > Time management topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. Note: QTIMZON also affects the timestamp applied to files in the Integrated File System (IFS). Changing The SMTP Port Number
Some installations use an SMTP port number other than the well‐known port 25. You can control the port number used by IBM iʹs SMTP stack by running the Configure TCP/IP (CFGTCP) command, selecting option 21. Configure related tables, then selecting option 1. Work with service table entries. Additional Mail Set Up Resources
The information in this chapter was drawn and condensed from the IBM i Information Center. You can find additional detail and more comprehensive coverage of IBM i configuration by going to the Networking > TCP/IP applications, protocols, and services > E‐mail topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. For Domino on IBM i users, our software uses IBM iʹs SMTP services to deliver mail. Valuable information on setting up Dominoʹs and IBM iʹs SMTP stack to coexist can be found in the IBM Redbook Chapter 4 Set Up
33
V5 TCP/IP Applications on the IBM eServer iSeries Server SG24‐6321 available at http://publib.boulder.ibm.com/eserver/ibmi.html. 34
Excel-erator Programmer's Guide and Reference
Chapter 5 Implementation
What's In This Chapter
This chapter describes how to implement Excel‐erator in your environment. The chapter: 











Gives an overview of implementation choices. Describes changing programs to process files. Describes manually processing files. Describes accessing files in the Integrated File System. Shows how to create PDM options for Excel‐eratorʹs commands. Shows how to use OPNQRYF to select specific records. Describes using format codes in headers and footers. Describes email address details. Describes adding line breaks to the message. Describes digitally signing the message. Describes a CL coding tip. Describes changing command defaults. Overview
Excel‐erator converts database files into spreadsheets. There are two commands that provide the conversion: 

Copy To Excel (CPYTOEXCEL) Send File Excel (SNDFEXCEL) To implement Excel‐erator in your environment you have two basic choices: 1.
Modify each program that creates files that will be converted to directly run the Copy To Excel (CPYTOEXCEL) or the Send File Excel (SNDFEXCEL) command. Pros
Cons
2.
The file is always processed as soon as it is created. Programs must be modified and recompiled. Manually run the Copy To Excel (CPYTOEXCEL) or the Send File Excel (SNDFEXCEL) command from a command line. Pros
Cons
Good for casual or on demand use, no program changes required. Requires manual operations and scheduling. See the following sections for a detailed discussion of the choices. Changing Programs
Excel‐erator can be implemented by changing the programs that create files to convert or email them directly. A typical batch Control Language (CL) program that creates a file would contain the following CL sequence: Chapter 5 Implementation
35
OVRDBF
OVRDBF
CLRPFM
CALL
...
FILE(INVENTORY) TOFILE(INVLIB/INVENTORY)
FILE(INVSTATUS) TOFILE(INVLIB/INVSTATUS)
FILE(INVLIB/INVSTATUS)
PGM(INVLIB/INV320)
...
If program INV320 generates file INVSTATUS then the following changes will convert the file to the /Excel/INV320 directory and create a file with the date and time created as the name: ...
OVRDBF
FILE(INVENTORY) TOFILE(INVLIB/INVENTORY)
OVRDBF
FILE(INVSTATUS) TOFILE(INVLIB/INVSTATUS)
CLRPFM
FILE(INVLIB/INVSTATUS)
CALL
PGM(INVLIB/INV320)
CPYTOEXCEL FROMFILE(INVLIB/INVSTATUS) +
TOOBJ('/Excel/INV320/InventoryStatus.xls')
...
The file is converted as soon as program INV320 has completed processing. Alternately, the following changes will email the file to ʹbillg@acme.comʹ: ...
OVRDBF
FILE(INVENTORY) TOFILE(INVLIB/INVENTORY)
OVRDBF
FILE(INVSTATUS) TOFILE(INVLIB/INVSTATUS)
CLRPFM
FILE(INVLIB/INVSTATUS)
CALL
PGM(INVLIB/INV320)
SNDFEXCEL SNDF((INVLIB/INVSTATUS)) +
TO((billg@acme.com))
...
The file is emailed as soon as program INV320 has completed processing. Manually Processing Files
Excel‐erator can be implemented by assigning an operator the task of manually converting files. The Copy To Excel (CPYTOEXCEL) and Send File Excel (SNDFEXCEL) commands can be run from any command line or from the XLERATOR menu. Accessing Integrated File System Files
Files are created in IBM iʹs Integrated File System (IFS). There is a variety of ways to access the contents of the IFS. The following common methods are described here: 




Accessing the file from a PC using IBM iʹs support for Windows Network Neighborhood (NetServer). Creating the file directly on a Windows machine using the IFSʹs QNTC file system. Transferring the file using FTP from a PC. Transferring the file using FTP from IBM i. Accessing the file from a PC using IBM i Access. Complete, detailed, information can be found in the Files and file systems > Integrated file system topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. Windows Network Neighborhood (NetServer)
IBM i Support for Windows Network Neighborhood (IBM i NetServer) allows a TCP/IP attached PC to access the Integrated File System using the file and print sharing built into Windows. 36
Excel-erator Programmer's Guide and Reference
IBM i NetServer support does not require you to install any additional software on your personal computer. Similarly, IBM i NetServer does not require any software other than base IBM i. Follow these guidelines to get IBM i NetServer set up. These instructions assume that you do not have access to Navigator for i. Whenever possible, you should use Navigator for i. Note: You must have *IOSYSCFG special authority to change any part of NetServer configuration. In addition, you must have *SECADM special authority to change the NetServer guest user profile. These changes will take effect the next time NetServer is started. 1.
2.
3.
Verify that IBM iʹs TCP/IP support is configured. Use the Work with Subsystems (WRKSBS) command to confirm that the QSERVER subsystem has started. [ i ] Verify that the NetServer name is unique on the network. To change the NetServer default server and default domain name, use the following command: [i]
[i]
CALL QZLSCHSN PARM(server_name domain_name
'text description or comment' X'00000000')
4.
To change NetServer guest support, use the following command: [i]
CALL QZLSCHSG PARM(guest_user_profile X'00000000')
Users who require the file and print‐sharing capabilities of NetServer, but do not have an IBM i user profile need a guest user profile. Note: The Guest User Profile should not have a password or any special authority. 5.
Stop and start NetServer, using the following commands: [i]
ENDTCPSVR SERVER(*NETSVR)
STRTCPSVR SERVER(*NETSVR)
To create additional shares you must use Navigator for i and follow these steps: 1.
2.
3.
4.
5.
6.
7.
Open a connection to your system in Navigator for i. [PC] Expand Network. [PC] Expand Servers. [PC] Click TCP/IP to retrieve a list of TCP/IP servers available. [PC] Right‐click NetServer and select Open. [PC] Right‐click Shared Objects and select New and then File. [PC] Use the General Properties page to configure the new file share with a name, description, access, maximum number of users, and directory path name. [PC]
Note: The Navigator for i online help provides more details about NetServer file share properties. Once a share has been created, map to it from your Windows PC by following these steps: 1.
2.
3.
Right‐click the Start button and choose Explore to open the Windows Explorer. [PC] Open the Tools pull‐down menu on the Windows Explorer and select Map network drive. [PC] Select the letter of a free drive for the file share. [PC]
Chapter 5 Implementation
37
4.
Enter the name of a NetServer file share. For example: [PC]
\\server_name\Sharename
Note: server_name is the NetServer name entered above, and Sharename is the file share name entered above. 5.
Click OK. [PC]
Alternately, you can use Network Neighborhood to access the share: 1.
2.
3.
Open Windows Network Neighborhood. Open QSYSTEM1 (Where QSYSTEM1 is the server name of NetServer on IBM i). [PC] Select a file share. [PC]
[PC]
QNTC File System
IBM iʹs QNTC file system allows the Integrated File System to write directly to Windows file shares (disk) as if it were local IBM i disk storage. Path (file) names in QNTC consist of the file system name, the Windows server name, the sharename, the directory and sub‐directory names, and the object name. Path (file) names have the following form: /QNTC/Servername/Sharename/MyDirectory/MyFile.pdf
Use the Make Directory (MKDIR) command to add a Windows machine to QNTC. For example: MKDIR DIR('/QNTC/NTSRV1')
Adds the NTSRV1 server into the QNTC file system directory structure to enable access of files and directories on that server. For additional detailed information, search IBM i Information Center for ʺQNTCʺ. FTP Using PC
FTP can be used from your PC to transfer the files to another system. In brief, the steps for retrieving the file /mydirectory/myfile.pdf from IFS to your PC are: 1.
Insure the IBM i FTP server is active by running this command from a command line: [i]
STRTCPSVR SERVER(*FTP)
2.
3.
Choose Start > Programs > Accessories > Command Prompt to open a command prompt. [PC] Open an FTP connection to IBM i by running (use your systemʹs name or IP address): [PC]
FTP system_name
4.
5.
Enter a user name and password as prompted. Change to binary (image) mode by running: [PC]
[PC]
binary
6.
38
[Enter]
[Enter]
Switch to IBM iʹs Integrated File System by running: [PC]
Excel-erator Programmer's Guide and Reference
quote site namefmt 1
7.
[Enter]
Retrieve the file by running: [PC]
get /mydirectory/myfile.pdf
8.
[Enter]
End FTP and command prompt by running: [PC]
quit
exit
[Enter]
[Enter]
For more details see Networking topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. FTP Using IBM i
FTP can be used from IBM i to transfer the files to another system interactively or in batch. The interactive procedure is similar to the PC procedure, using ʺputʺ instead of ʺgetʺ. In brief, the steps for transferring the file /mydirectory/myfile.pdf from IFS to another system in batch are: 1.
Create a source member containing the FTP commands that you would otherwise have to type at the terminal during an interactive session with the target server. By way of example, we use the following command sequence in member FTPCMDS in QGPL/QCLSRC. [i]
user password
binary
namefmt 1
put /mydirectory/myfile.pdf
quit
2.
Add the following statements to your program: [i]
...
OVRDBF FILE(INPUT) TOFILE(QGPL/QCLSRC) MBR(FTPCMDS)
OVRDBF FILE(OUTPUT) TOFILE(QGPL/QCLSRC) MBR(FTPLOG)
FTP
RMTSYS(system_name)
...
For more details see Networking > TCP/IP applications, protocols, and services > FTP topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. IBM i Access
IBM i Access includes software that connects to IBM i and makes the integrated file system available to the PC. For more information see IBM i Access topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. Creating PDM Options For Excel-erator
IBMʹs Program Development Manager (PDM) allows creation of user‐defined options. For additional information, see iSeries Programming Development Manager Userʹs Guide SC09‐2133. Chapter 5 Implementation
39
Creating A PDM Option For CPYTOEXCEL
The following steps will create the user‐defined option ʺXLʺ which will submit a job to run the CPYTOEXCEL command from within PDM when ʺXLʺ is keyed next to a member name: 


Enter PDM by using the WRKMBRPDM command. Press F16 to work with user defined options. Press F6 to create a new user defined option. Create User-Defined Option
Type changes, press Enter.
Option
. . . . . . . . .
XL
Option to create
Command . . . . . . . . .
/* Excel-erator CPYTOEXCEL Batch
sbmjob job(&N) jobd(&J) cmd(xlerator/cpytoexcel fromfile(&l/&f)
toobj('/Excel/*filelib.*file.*mbr.xls') frommbr(&n) crtdir(*yes))
F3=Exit


F4=Prompt
*/
F12=Cancel
Key the user defined option definition as shown above, and press Enter. Press F3 to exit the Work with User‐Defined Options display. Now key XL in the option field for members to submit a batch conversion. Creating A PDM Option For SNDFEXCEL
The following steps will create the user‐defined option ʺXSʺ which will prompt the SNDFEXCEL command from within PDM when ʺXSʺ is keyed next to a file name: 


40
Enter PDM by using the WRKMBRPDM command. Press F16 to work with user defined options. Press F6 to create a new user defined option. Excel-erator Programmer's Guide and Reference
Create User-Defined Option
Type changes, press Enter.
Option
. . . . . . . . .
XS
Option to create
Command . . . . . . . . .
/* Excel-erator SNDFEXCEL
?xlerator/sndfexcel sndf((&l/&n))
F3=Exit


F4=Prompt
*/
F12=Cancel
Key the user defined option definition as shown above, and press Enter. Press F3 to exit the Work with User‐Defined Options display. Now key XS in the option field for a file to send it. Selecting Records With OPNQRYF
In some cases, you may wish to create a spreadsheet containing a subset of records from the underlying database file. This can be accomplished using IBM iʹs Open Query File (OPNQRYF) command. As an example, suppose you wish to select only the records for customer A1234 from the invoice records file QGPL/QINVREC, which contains the field CUST. To accomplish this with OPNQRYF, run the following commands: ...
FILE(QINVREC) TOFILE(QGPL/QINVREC) OVRSCOPE(*JOB)
SHARE(*YES)
OPNQRYF
FILE((QINVREC)) QRYSLT('CUST *EQ ''A1234''')
OPNSCOPE(*JOB)
CPYTOEXCEL FROMFILE(QINVREC)
TOOBJ('/Excel/CustA1234InvoiceRecords.xls')
CLOF
OPNID(QINVREC)
DLTOVR
FILE(QINVREC) LVL(*JOB)
...
OVRDBF
This procedure also works with the Send File Excel (SNDFEXCEL) command. Format Codes In Headers And Footers
Several of the transforms support the use of format codes in the print headers and print footers that can be entered on the PRTHEADER() and PRTFOOTER() parameters. Some of the codes and their meaning are: Format Code
&L
&C
Description
Left‐aligns the characters that follow. Centers the characters that follow. Chapter 5 Implementation
41
&R
&B
&I
&D
&T
&F
&A
&P
&&
&N
Right‐aligns the characters that follow. Turns bold printing on or off. Turns italic printing on or off. Prints the current date. Prints the current time. Prints the name of the document. Prints the name of the worksheet. Prints the page number. Prints a single ampersand. Prints the total number of pages in the document. As an example, to generate a spreadsheet with page numbers as the print footer, specify the following CPYTOEXCEL ... PRTFOOTER('Page: &P of &N')
SNDFEXCEL ... PRTFOOTER('Page: &P of &N')
Email Addresses
There are three choices for addressing mail created by Excel‐erator, direct SMTP addressing, special values, and directory entries stored in the system distribution directory. With direct SMTP addressing, you enter the email address directly on the parameter, no additional address set up is required. Excel‐
erator supports the full range of email address formats, including route specification and RFC3490 Internationalizing Domain Names in Applications (IDNA). Valid formats for email addresses include: 




ʹmali@acme.comʹ ʹ<mali@acme.com>ʹ ʹMohammed Ali <mali@acme.com>ʹ ʹʺMohammed Aliʺ <mali@acme.com>ʹ ʹMohammed Ali (I am the Greatest) <mali@acme.com>ʹ In all of these examples the message is delivered to the mailbox mali@acme.com. Address Resolution For Special Values
Excel‐erator supplies several special values for specifying email addresses. For example, *CURRENT is the default value on the From (originator) Address parameter. Excel‐erator uses the following steps to resolve an email address for special values that imply an IBM i user profile. 


If the user profile implied by the special value is enrolled in the system distribution directory and the entry contains an email address the email address is used. If the user profile implied by the special value is enrolled in the system distribution directory and the entry does not contain an email address an IBM i style address is generated in the form: usrid?address@host.domain. If the user profile implied by the special value is not enrolled in the system distribution directory an email address is generated in the form: userprofile@host.domain Note: In the above, host and domain are taken from the values entered on the CFGTCP option 12 panel. Therefore, to have the correct email address resolved, you should add or update a system distribution directory entry for each user profile that will be referenced by the special values you will use. Usually this is every user profile that will send email. 42
Excel-erator Programmer's Guide and Reference
To see the list and meaning of special values supported on a particular parameter, prompt the command and display help information by pressing F1. Setting Up Directory Entry Email Addresses For Local Users
IBM iʹs system distribution directory can contain addressing information for users. Directory entries can be created for users who are local to the system (have an IBM i user profile) and for users who are remote (do not have an IBM i user profile). Local users can receive their mail from the system using IBM iʹs POP server or from a remote mail application such as Exchange. You should set up each local user who will be sending email to insure that the apparent ʺFrom:ʺ address in the email will be correct and to insure that replies reach the sender. To add a directory entry for user profile MYUSER, run the following command: (for this example, assume the userʹs email address is billg@acme.com): ADDDIRE USRID(MYUSER MYSYSTEM) USRD('Sample entry')
USER(MYUSER) SYSNAME(*LCL)
MSFSRVLVL(*SYSMS) PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'billg')
(SMTPDMN SMTP 'acme.com'))
Note: If you are running Lotus Domino for IBM i, run: ADDDIRE USRID(MYUSER MYSYSTEM) USRD('Sample entry')
USER(MYUSER) SYSNAME(*LCL)
MSFSRVLVL(*DOMINO) PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'billg')
(SMTPDMN SMTP 'acme.com'))
To update an existing directory entry for user profile MYUSER, run the following command: CHGDIRE USRID(MYUSER MYSYSTEM)
MSFSRVLVL(*SYSMS) PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'billg')
(SMTPDMN SMTP 'acme.com'))
Setting Up Directory Entry Email Addresses For Remote Users
You do not need to set up remote user in order to send them email, but it will enable you to use distribution lists. To add a directory entry for a remote user who will receive email mail from IBM i, run the following command (for this example, assume the userʹs email address is johnp@acme.com): ADDDIRE USRID(RMT1 EMAIL) USRD('Sample entry 2')
USER(*NONE) SYSNAME(TCPIP)
MSFSRVLVL(*SYSMS) PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'johnp')
(SMTPDMN SMTP 'acme.com'))
Note: The choice of USRID(RMT1 EMAIL) is arbitrary, select names that are convenient. The system name must be TCPIP. To add a directory entry for a Domino user who does not have an IBM i user profile, run the following command (for this example, assume the userʹs email address is suej@acme.com): ADDDIRE USRID(DOMINO EMAIL) USRD('Sample entry 3')
USER(*NONE) SYSNAME(TCPIP)
MSFSRVLVL(*DOMINO) PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'suej')
(SMTPDMN SMTP 'acme.com'))
Note: The choice of USRID(DOMINO EMAIL) is arbitrary, select names that are convenient. The system name must be TCPIP. Chapter 5 Implementation
43
Using Distribution Lists
Once you have directory entries set up you can also set up distribution lists. These are lists of recipients (both local and remote) that can be maintained independently of the programs that use the lists. By sending to a distribution list, you send to each entry on the list. Like directory entries, distribution list IDs have two parts. To make it convenient to manage the system, set up a naming convention for list IDs; for example, INV320 REPORT and INV330 REPORT could be list IDs for recipients of the INV320 and INV330 reports respectively. Such a convention allows lists to be easily associated with their use. Suppose that the INV320 report should be sent to billg@acme.com and to johnp@acme.com. To create a distribution list to reflect this, run the following commands: 1.
Create the distribution list: CRTDSTL LSTID(INV320 REPORT)
LSTD('INV320 report distribution')
2.
Add 2 entries to the distribution list: ADDDSTLE LSTID(INV320 REPORT)
USRID((MYUSER MYSYSTEM) (RMT1 EMAIL))
You are now ready to send to the two users with one command by specifying the To (distribution list) parameter: (other command parameters) ... TOUSRID(INV320 REPORT)
Adding Line Breaks to the Message
When Using *TEXTPLAIN
The following CL program fragment shows how to create a message variable that contains a line break (carriage return/line feed pair): ...
VAR(&MSG) TYPE(*CHAR) LEN(2048)
VAR(&CRLF) TYPE(*CHAR) LEN(2) VALUE(X'0D25')
VAR(&LIN1) TYPE(*CHAR) LEN(72) VALUE('First line.')
VAR(&LIN2) TYPE(*CHAR) LEN(72) VALUE('Second line.')
...
CHGVAR VAR(&MSG) VALUE(&LIN1 │< &CRLF │< &LIN2)
...
DCL
DCL
DCL
DCL
The resulting message is: First line.
Second line.
The equivalent RPG is: ...
C
C
C
move
movel
movel
x'0d25'
crlf
'First line.' lin1
'Second line.'lin2
2
72
72
eval
msg ═ %trimr(lin1) + crlf + lin2
...
C
...
44
Excel-erator Programmer's Guide and Reference
When Using *TEXTHTML
The following CL program fragment shows how to create a message variable that contains a line break. ...
VAR(&MSG) TYPE(*CHAR) LEN(2048)
VAR(&BR) TYPE(*CHAR) LEN(2) VALUE('<br>')
VAR(&LIN1) TYPE(*CHAR) LEN(72) VALUE('First line.')
VAR(&LIN2) TYPE(*CHAR) LEN(72) VALUE('Second line.')
...
CHGVAR VAR(&MSG) VALUE(&LIN1 │< &BR │< &LIN2)
...
DCL
DCL
DCL
DCL
The resulting message is: First line.
Second line.
The equivalent RPG is: ...
C
C
C
move
movel
movel
'<br>'
br
'First line.' lin1
'Second line.'lin2
eval
msg ═ %trimr(lin1) + br + lin2
4
72
72
...
C
...
Digitally Signing The Message
Email produced by Excel‐erator can optionally be digitally signed using S/MIME Signed Message format. S/MIME (Secure / Multipurpose Internet Mail Extensions) is a standard for public key encryption and signing of email encapsulated in MIME. A signed message is an ordinary message with a digital signature added by the sender. The signature has two purposes: it identifies the sender, and it verifies that the content of the message has not been altered since the message was sent. You create digitally signed email by specifying an Application ID when the email is created. There are two ways to accomplish this: at the command level and at the system (or LPAR) level. The command level overrules the system level. For command level, specify an Application ID directly on the send commandʹs new Signing key (SGNKEY) parameter. For the system level, specify an Application ID on the CHGXL1DFT commandʹs new Signing key (SGNKEY) parameter. The shipped default values for the Signing key (SGNKEY) parameters are *DEFAULT and *NONE respectively. Application ID refers to the name you have given to a digital certificate when placing it in the *OBJECTSIGNING Certificate Store using IBM iʹs Digital Certificate Manager (DCM). DCM is option 34 of IBM i. You can determine if DCM has been installed by running the Display Software Resources (DSPSFWRSC) command. Complete information on setting up DCM, creating and storing certificates and adding Application IDs, can be found in the Security > Digital Certificate Manager topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. CL Coding Tip
Many of our commands accept a variable number of values for a given parameter. For example, the Send Spool Mail (SNDSPLMAIL) command accepts up to 300 email addresses on the recipient parameter. When writing CL programs, the problem of how to code for a variable number of email addresses without coding the SNDSPLMAIL command multiple times (once for each address count) arises. The Chapter 5 Implementation
45
solution is a little known CL trick for coding ʺno valueʺ in a variable. ʺNo valueʺ is represented in CL by ʹ*Nʹ. Consider the following program fragment: PGM
DCL
DCL
DCL
VAR(&ADD1) TYPE(*CHAR) LEN(128) VALUE('*N')
VAR(&ADD2) TYPE(*CHAR) LEN(128) VALUE('*N')
VAR(&ADD3) TYPE(*CHAR) LEN(128) VALUE('*N')
...
CHGVAR
VAR(&ADD1) VALUE(NOBODY@GUMBO.COM)
...
SNDSPLMAIL FILE(QPDSPLIB) TRANSFORM(*TXT) +
TOSMTPNAME((&ADD1) (&ADD2) (&ADD3))
...
ENDPGM
Since &ADD2 and &ADD3 contain ʹ*Nʹ they are treated as if they were not specified on the command and the email is sent to only one address. Changing Command Defaults
As with any CL command, you can change the default values of the commands found in our products. You do this using the IBM i Change Command Default (CHGCMDDFT) command. But before you do, there are some gotchas (slang term for ʺI got youʺ: a trap) you should be aware of. You WILL lose the change each time a new release of the product is installed, and you COULD lose the change when PTFs are applied to the product. You must then reapply the default change. As an example, to change the default transform on SpoolMailʹs SNDSPLMAIL command from *TXT to *PDFA4, run the following: CHGCMDDFT
CMD(SNDSPLMAIL) NEWDFT('TRANSFORM(*PDFA4)')
GUMBO recommends AGAINST changing command defaults, we know from the calls for support we receive that this regularly causes problems for customers. 46
Excel-erator Programmer's Guide and Reference
Chapter 6 Conversion
What's In This Chapter
This chapter describes the file conversion available with Excel‐erator. The chapter: 








Gives an overview of the available conversions. Describes *BIFF8 conversion details and limitations. Describes *CSVUTF8 conversion details and limitations. Describes *CSVUTF8M conversion details and limitations. Describes *CSVRFC conversion details and limitations. Describes *CSVRFCQ conversion details and limitations. Describes *XMLSS conversion details and limitations. Describes *OOXML conversion details and limitations. Describes *BIFF4 conversion details and limitations. Overview
Excel‐erator retrieves the requested database file from IBM i and converts the data into a PC file in spreadsheet format. The transform parameter determines the type of conversion performed and therefore the format of the generated spreadsheet. The supported formats are: Transform
*BIFF8
*CSVUTF8
*CSVUTF8M
*CSVRFC
*CSVRFCQ
*XMLSS
*OOXML
*BIFF4
Format Description
Microsoftʹs Binary Interchange File Format Version 8, the format used by Excel version 8.0 (Excel 97/98), Excel 9.0 (Excel 2000/2001), Excel 10.0 (Excel XP/v.X) and Excel 11.0 (Excel 2003/2004). Comma Separated Values (CSV) format. Data is converted to UTF‐8. Trailing blanks are trimmed. Comma Separated Values (CSV) format. Data is converted to UTF‐8 and Byte Order Mark xEFBBBF is inserted at the start of the file. Trailing blanks are trimmed. Comma Separated Values (CSV) format. Data is converted to US‐ASCII in strict compliance with RFC4180 Common Format and MIME Type for Comma‐Separated Values (CSV) Files. Quoting is avoided unless need data containing quotes. Trailing blanks are trimmed. Comma Separated Values (CSV) format. Data is converted to US‐ASCII in strict compliance with RFC4180 DOUBLE QUOTED Common Format and MIME Type for Comma‐Separated Values (CSV) Files. Character data is always quoted. Trailing blanks are trimmed. Microsoftʹs Excel specific ʺXML Spreadsheet formatʺ introduced with Excel 2002 and Excel 2003. Office Open XML developed by Microsoft. Excel‐erator implements the ISO/IEC 29500:2008 Strict specification, suitable for use with Excel 2010 and suitable for use with Excel 2007 if dates are not present in the spreadsheet. See http://en.wikipedia.org/wiki/Office_Open_XML for additional information. Microsoftʹs Binary Interchange File Format Version 4, the format used by Excel version 4.0 (Excel 4.0). Note: Use *BIFF8 instead of *BIFF4. *BIFF4 is included for compatibility with existing software and is no longer being enhanced. For all transforms, each record in the database file creates a row in the spreadsheet, while each selected field in the record creates a cell in the row. Logical files are supported, but only if they have a single record format. Our calls to the underlying IBM i APIs specify that overrides should be processed when retrieving file information and data. Not all parameters are applicable to all transforms: Chapter 6 Conversion
47
Figure: Parameter Applicability By Transform
┌────────────┬───────────────────────────────┬─────────┐
│
│ Transform
│
│
│
├───┬───┬───┬───┬───┬───┬───┬───┤
│
│
│*│*│*│*│*│*│*│ │
│
│
│B│C│C│C│X│O│B│ │
│
│
│I│S│S│S│M│O│I│ │
│
│
│F│V│V│V│L│X│F│ │
│
│F│U│U│R│S│M│F│ │
│
│
│
│8│T│T│F│S│L│4│ │
│
│
│ │F│F│C│ │ │ │ │
│
│
│ │8│8│ │ │ │ │ │
│
│
│ │ │M│ │ │ │ │ │
│
│ Parameter │ │ │ │ │ │ │ │ │ MsgId │
├────────────┼───┼───┼───┼───┼───┼───┼───┼───┼─────────┤
│ COLHDG
│YES│YES│YES│YES│YES│YES│YES│ │ XL17006 │
│ SHEETNAME │YES│ ─ │ ─ │ ─ │YES│YES│ ─ │ │ XL17004 │
│ SHEETTITLE │YES│ ─ │ ─ │ ─ │YES│YES│ ─ │ │ XL17005 │
│ ADDWS
│YES│ ─ │ ─ │ ─ │YES│YES│ ─ │ │ XL17003 │
│ PRTHEADER │YES│ ─ │ ─ │ ─ │YES│YES│YES│ │ XL17007 │
│ PRTFOOTER │YES│ ─ │ ─ │ ─ │YES│YES│YES│ │ XL17008 │
│ FONT
│YES│ ─ │ ─ │ ─ │YES│YES│YES│ │ XL17009 │
│ COMMENT
│YES│ ─ │ ─ │ ─ │YES│YES│YES│ │ XL17010 │
│ FILESHARE │YES│ ─ │ ─ │ ─ │ ─ │ ─ │YES│ │ XL17014 │
│ COLHDGFMT │YES│ ─ │ ─ │ ─ │YES│YES│YES│ │ XL17015 │
│ PALETTE
│YES│ ─ │ ─ │ ─ │YES│YES│YES│ │ XL17016 │
│ CSVSEPCHR │ ─ │YES│YES│ ─ │ ─ │ ─ │ ─ │ │ SCV7001 │
│ PAGESETUP │YES│ ─ │ ─ │ ─ │YES│YES│ ─ │ │ XL17017 │
│ FREEZEPANE │YES│ ─ │ ─ │ ─ │YES│YES│ ─ │ │ XL17018 │
│ TRGCCSID │ ─ │ ─ │ ─ │ ─ │ ─ │ ─ │YES│ │ XL17011 │
│ SRCCCSID │ ─ │ ─ │ ─ │ ─ │ ─ │ ─ │YES│ │ XL17012 │
└────────────┴───┴───┴───┴───┴───┴───┴───┴───┴─────────┘
The following sections describe the conversions in more detail. *BIFF8 Conversion
Details
The *BIFF8 conversion creates Microsoft Excel 2003/2004 spreadsheets. The first rows of the spreadsheet contain the title lines specified on the Sheet title (SHEETTITLE) parameter, followed by column headings specified on the Column headings (COLHDG) parameter, which serve as column headings for the cells in subsequent rows. The generated spreadsheet contains the fields selected from the input fileʹs record format. Fields containing character data (types A, J, E, O, and G) are converted to BIFF8ʹs internal encoding based on the fieldʹs coded character set identifier (CCSID). The conversion of fields to cells depends on the fieldʹs data type: Data Type
A (Character)
Processing
Convert to a text cell in BIFF8ʹs internal format based on the CCSID of the field. Trailing blanks are trimmed. P (Packed decimal) Convert to a number cell. S (Zoned decimal) Convert to a number cell. B (Binary)
Convert to a number cell. F (Floating point)
Convert to a number cell. H (Hexadecimal)
Copy to a text cell without conversion. L (Date)
Convert to a date cell with *ISO formatting. T (Time)
Convert to a time cell with *ISO formatting. Z (Timestamp)
Convert to a date cell with *ISO formatting. The microseconds are omitted. J (DBCS-Only)
Convert to a text cell in BIFF8ʹs internal format based on the CCSID of the field. Trailing blanks are trimmed. E (DBCS-Either)
Convert to a text cell in BIFF8ʹs internal format based on the CCSID of the field. Trailing blanks are trimmed. O (DBCS-Open)
Convert to a text cell in BIFF8ʹs internal format based on the CCSID of the field. Trailing blanks are 48
Excel-erator Programmer's Guide and Reference
G (DBCS-Graphic)
1 (BLOB)
2 (CLOB)
3 (DBCLOB)
4 (Datalink)
trimmed. Convert to a text cell in BIFF8ʹs internal format based on the CCSID of the field. Trailing blanks are trimmed. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Limitations
Microsoftʹs BIFF8 spreadsheet format and Excel‐erator impose certain limits on the conversion process. These are: 




A spreadsheet may have no more than 64 worksheets. When a database file has more than 65536 records it is split into multiple worksheets of 65536 rows each. This gives an effective limit of 2,097,152 records. A spreadsheet may have no more than 256 columns. All BIFF8 numbers are represented internally as long doubles, which can give slightly different decimal position results. That is, the IBM i value 123.456 might show up as 123.456001 when viewed in the cell. BIFF8ʹs format strings do not support all the features of IBM iʹs edit words. *CSVUTF8 Conversion
Details
The *CSVUTF8 conversion creates Comma Separated Values spreadsheets in compliance with RFC4180 Common Format and MIME Type for Comma‐Separated Values (CSV) Files with the exceptions noted below. The first rows of the spreadsheet can optionally contain column headings as specified on the Column headings (COLHDG) parameter. These serve as column headings for the cells in subsequent rows. The generated spreadsheet contains the fields selected from the input fileʹs record format. The exceptions are: 

While RFC4180 only allows US‐ASCII, fields containing character data (types A, J, E, O, and G) are converted to UTF8 based on the fieldʹs coded character set identifier (CCSID). This insures that any and all character data can be included. If the character data happens to all be US‐ASCII (all single byte UTF8), the resulting file is strictly compliant with RFC4180. While RFC4180 specifies a separator character of comma (ʹ,ʹ), alternate separator characters can be specified using the CSVSEPCHR() parameter. The conversion of fields to values depends on the fieldʹs data type. In all cases, quoting rules are applied after conversion, as needed: Data Type
A (Character)
Processing
Convert to UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Fields with embedded separator characters are enclosed within double‐quote characters. Fields with embedded double‐quote characters are enclosed within double‐quote characters, and each of the embedded double‐quote characters is represented by a pair of double‐quote characters. Fields with embedded line breaks are enclosed within double‐quote characters. P (Packed decimal) Convert to a UTF8 character value with EDTCDE() or EDTWRD() applied if specified. S (Zoned decimal) Convert to a UTF8 character value with EDTCDE() or EDTWRD() applied if specified. B (Binary)
Convert to a UTF8 character value with EDTCDE() or EDTWRD() applied if specified. F (Floating point)
Convert to a UTF8 character value in external floating‐point format. Chapter 6 Conversion
49
H (Hexadecimal)
L (Date)
T (Time)
Z (Timestamp)
J (DBCS-Only)
E (DBCS-Either)
O (DBCS-Open)
G (DBCS-Graphic)
1 (BLOB)
2 (CLOB)
3 (DBCLOB)
4 (Datalink)
Copy without conversion. Convert to a UTF8 character value based on the specified DATFMT() and DATSEP(). Convert to a UTF8 character value based on the specified TIMFMT() and TIMSEP(). Convert to a UTF8 character value. Converted to UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Converted to UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Converted to UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Converted to UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Omitted and a warning is issued. Omitted and a warning is issued. Omitted and a warning is issued. Omitted and a warning is issued. Limitations
Comma Separated Value and Excel‐erator impose certain limits on the conversion process. These are: 

A spreadsheet may have only one database member. Bolding requests are ignored. *CSVUTF8M Conversion
Details
The *CSVUTF8M conversion is identical to *CSVUTF8 in all respects except one. For *CSVUTF8M a byte order mark of xEFBBBF is placed at the beginning of the generated file. Limitations
Same as *CSVUTF8 limitations listed above. *CSVRFC Conversion
Details
The *CSVRFC conversion is identical to *CSVUTF8 in all respect except one. For *CSVRFC if any data can not be converted to US‐ASCII (CCSID=367), the conversion process fails and a spreadsheet is not generated. Character data is only quoted if it contains the quote character (the Microsoft Excel method). Limitations
Same as *CSVUTF8 limitations listed above with two additions: 

All data must convert to US‐ASCII (CCSID=367). The separator character must be *COMMA (ʹ,ʹ). *CSVRFCQ Conversion
Details
The *CSVRFCQ conversion is identical to *CSVRFC in all respect except one. For *CSVRFCQ Character data is always quoted. Limitations
Same as *CSVRFC limitations listed above. 50
Excel-erator Programmer's Guide and Reference
*XMLSS Conversion
Details
The *XMLSS conversion creates Microsoftʹs Excel specific ʺXML Spreadsheet formatʺ introduced with Excel 2002 and Excel 2003. The first rows of the spreadsheet contain the title lines specified on the Sheet title (SHEETTITLE) parameter, followed by column headings specified on the Column headings (COLHDG) parameter, which serve as column headings for the cells in subsequent rows. The generated spreadsheet contains the fields selected from the input fileʹs record format. Fields containing character data (types A, J, E, O, and G) are converted to UTF8 based on the fieldʹs coded character set identifier (CCSID). The conversion of fields to cells depends on the fieldʹs data type: Data Type
A (Character)
P (Packed decimal)
S (Zoned decimal)
B (Binary)
F (Floating point)
H (Hexadecimal)
L (Date)
T (Time)
Z (Timestamp)
J (DBCS-Only)
E (DBCS-Either)
O (DBCS-Open)
G (DBCS-Graphic)
1 (BLOB)
2 (CLOB)
3 (DBCLOB)
4 (Datalink)
Processing
Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Convert to a Number cell. Convert to a Number cell. Convert to a Number cell. Convert to a Number cell. Convert to a String cell as a character representation. Convert to a DateTime cell. Convert to a DateTime cell. Convert to a DateTime cell. The microseconds are truncated to three positions. Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Limitations
Microsoftʹs XML Spreadsheet format and Excel‐erator impose certain limits on the conversion process. These are: 

A spreadsheet may have no more than 64 worksheets. XML Spreadsheet formatʹs format strings do not support all the features of IBM iʹs edit words. While XML Spreadsheet format does not impose limits on the number of rows or columns in a spreadsheet, various file viewers do, most prominently Excel. For example, Excel 2007 imposes a limit of 1,048,578 rows and 16,384 columns. *OOXML Conversion
Details
The *OOXML conversion creates Office Open XML developed by Microsoft. Excel‐erator implements the ISO/IEC 29500:2008 Strict specification, suitable for use with Excel 2010. It is also suitable for use with Excel 2007 if dates are not present in the spreadsheet. See http://en.wikipedia.org/wiki/Office_Open_XML for additional information. The first rows of the spreadsheet contain the title lines specified on the Sheet title (SHEETTITLE) parameter, followed by column headings specified on the Column headings (COLHDG) parameter, which serve as column headings for the cells in subsequent rows. The generated spreadsheet Chapter 6 Conversion
51
contains the fields selected from the input fileʹs record format. Fields containing character data (types A, J, E, O, and G) are converted to UTF8 based on the fieldʹs coded character set identifier (CCSID). The conversion of fields to cells depends on the fieldʹs data type: Data Type
A (Character)
P (Packed decimal)
S (Zoned decimal)
B (Binary)
F (Floating point)
H (Hexadecimal)
L (Date)
T (Time)
Z (Timestamp)
J (DBCS-Only)
E (DBCS-Either)
O (DBCS-Open)
G (DBCS-Graphic)
1 (BLOB)
2 (CLOB)
3 (DBCLOB)
4 (Datalink)
Processing
Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Convert to a Number cell. Convert to a Number cell. Convert to a Number cell. Convert to a Number cell. Convert to a String cell as a character representation. Convert to an ISO DateTime cell. Convert to an ISO DateTime cell. Convert to an ISO DateTime cell. The microseconds are truncated to three positions. Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Convert to a String cell in UTF8 based on the CCSID of the field. Trailing blanks are trimmed. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Limitations
Office Open XML format and Excel‐erator impose certain limits on the conversion process. These are: 


A spreadsheet may have no more than 64 worksheets. Office Open XML does not support encryption. Office Open XML format strings do not support all the features of IBM iʹs edit words. While Office Open XML format does not impose limits on the number of rows or columns in a spreadsheet, various file viewers do, most prominently Excel. For example, Excel 2007 imposes a limit of 1,048,578 rows and 16,384 columns. *BIFF4 Conversion
Note: Use *BIFF8 instead of *BIFF4. *BIFF4 is included for compatibility with existing software and is no longer being enhanced. Details
The *BIFF4 conversion creates Microsoft Excel 4.0 spreadsheets. The first rows of the spreadsheet contain the title lines specified on the Sheet title (SHEETTITLE) parameter, followed by column headings specified on the Column headings (COLHDG) parameter, which serve as column headings for the cells in subsequent rows. The generated spreadsheet contains the fields selected from the input fileʹs record format. These are converted from EBCDIC to ASCII based on the values specified in the commandʹs Target coded character set id (TRGCCSID), and Source coded character set id (SRCCCSID) parameters. The conversion of fields to cells depends on the fieldʹs data type: Data Type
A (Character)
Processing
Convert to a text cell based on the SRCCCSID and TRGCCSID. The data is trimmed if it exceeds the Excel maximum of 255. Trailing blanks are trimmed. P (Packed decimal) Convert to a number cell. S (Zoned decimal) Convert to a number cell. 52
Excel-erator Programmer's Guide and Reference
B (Binary)
F (Floating point)
H (Hexadecimal)
L (Date)
T (Time)
Z (Timestamp)
J (DBCS-Only)
E (DBCS-Either)
O (DBCS-Open)
G (DBCS-Graphic)
1 (BLOB)
2 (CLOB)
3 (DBCLOB)
4 (Datalink)
Convert to a number cell. Convert to a number cell. Copy to a text cell without conversion. Convert to a date cell with *ISO formatting. Convert to a time cell with *ISO formatting. Convert to a date cell with *ISO formatting. The microseconds are omitted. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Omit and issue a warning. Limitations
Microsoftʹs BIFF4 spreadsheet format and Excel‐erator impose certain limits on the conversion process. These are: 






Double byte character set data is not supported. A spreadsheet may have only one worksheet. A spreadsheet may have no more than 65536 rows. A spreadsheet may have no more than 256 columns. A character field may have a maximum length of 255. All BIFF4 numbers are represented internally as long doubles, which can give slightly different decimal position results. That is, the IBM i value 123.456 might show up as 123.456001 when viewed in the cell. BIFF4ʹs format strings do not support all the features of IBM iʹs edit words. Chapter 6 Conversion
53
Chapter 7 Commands
What's In This Chapter
This chapter describes the control language (CL) commands supplied by Excel‐erator. The commands are arranged in alphabetic order by command name (mnemonic). Each description includes environment and threadsafe classification, a brief general description, detailed parameter explanations, examples and message information. Additional explanatory material can be found in the Programming > Control Language > CL Concepts > CL Commands > CL command information and documentation topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. Chapter 7 Commands
55
Change Excel-erator Authorization (CHGXL1AUT)
Where allowed to run: All environments (*ALL) Threadsafe: No The Change Excel‐erator Authorization (CHGXL1AUT) command changes the authorization code for Excel‐erator. The command is used to extend a demonstration period or to permanently authorize Excel‐
erator for a system or a partition. The proposed authorization information is tested against the authorization algorithm to confirm that it will authorize Excel‐erator. If the test fails, no change is made. Parameters
Keyword Description Choices Notes AUTH Authorization code Hexadecimal value Required, Positional 1 EXPDAT Expiration date (CCYYMMDD) Character value, *NONE Optional, Positional 2 LICTYP License type *SYS, *LPAR Optional, Positional 3 PRCMAX Processor maximum capacity Decimal number Optional, Positional 4 Authorization code (AUTH)
Specifies the authorization code to use. The authorization code is 8 hex digits that may be entered in upper or lower case. This is a required parameter. hexadecimal-value Specify the case insensitive authorization code. Expiration date (CCYYMMDD) (EXPDAT)
Specifies the date on which the authorization expires. *NONE
date
The authorization is permanent. The date on which the authorization expires in CCYYMMDD format. License type (LICTYP)
Specifies the type of license that is authorized. *SYS
The authorization is for a system wide license, which enables any and all partitions on the system but is specific to the processor group. Note: The authorization code must be entered in each partition. *LPAR
The license is specific to one of the partitions on the system and specific to a number of processors within the partition. A partition license must be entered in the partition for which it is intended. Processor maximum capacity (PRCMAX)
Specifies the maximum processor capacity for which the partition is licensed. The value is expressed in terms of processors where 1.00 is 100% of a processorʹs capacity or the same as 1 processor, .50 is 50% of a processorʹs capacity or .5 processors, 2.00 is 200% of a processorʹs capacity or 2 processors, etc. decimal-number Specify the maximum processor capacity. 56
Excel-erator Programmer's Guide and Reference
Examples
Example 1:
CHGXL1AUT
AUTH(01234567)
This command changes the authorization code to a permanent system wide license code. Example 2:
CHGXL1AUT
AUTH(01234567) LICTYP(*LPAR) PRCMAX(1.3)
This command changes the authorization code to a permanent partition only license code for 1.3 processors in the current partition. Error messages
*ESCAPE messages
AUT9909
Excel‐erator authorization change was not performed. Chapter 7 Commands
57
Change Excel-erator Default (CHGXL1DFT)
Where allowed to run: All environments (*ALL) Threadsafe: No The Change Excel‐erator Default (CHGXL1DFT) command changes values used by Excel‐erator to control processing and other activities. Parameters
Keyword Description Choices Notes SGNKEY Signing key Single values: *SAME, *NONE Other values: Element list Optional, Positional 1 Element 1: Application ID Character value Signing key (SGNKEY)
Specifies the default digital certificate used to sign email. The signature included with the email allows the recipient to validate the identity of the sender and provides additional assurance that the email has not been tampered with after it is signed. A certificate is referenced by specifying the name (Application ID) of an object signing application created using IBM iʹs Digital Certificate Manager. *SAME
*NONE
application-id
The value is not changed. No signing operation is performed. Specify the application identifier to use in the signing operation. Examples
Example 1:
CHGXL1DFT
SGNKEY(*NONE)
This command removes the default digital certificate. By default, emails are not signed. Example 2:
CHGXL1DFT
SGNKEY(WIDGETEMAIL)
This command changes the application identifier used to locate a digital certificate used to sign email, by default. Error messages
*ESCAPE messages
XL12016
58
Unable to change Excel‐erator defaults. Excel-erator Programmer's Guide and Reference
Check Excel-erator Authorization (CHKXL1AUT)
Where allowed to run: All environments (*ALL) Threadsafe: No The Check Excel‐erator Authorization (CHKXL1AUT) command executes Excel‐eratorʹs authorization verification function. This allows you to determine whether and how the product is authorized for use. Parameters
Keyword Description Choices Notes MSGQ Message queue Single values: *NONE Other values: Qualified object name Optional, Positional 1 Qualifier 1: Message queue Name Qualifier 2: Library Name, *LIBL, *CURLIB Message queue (MSGQ)
Specifies a message queue that should receive messages if the product is not permanently authorized. Single values
*NONE
Messages are not sent to an external message queue. Qualifier 1: Message queue
name
Specify the name message queue that receives messages. Qualifier 2: Library
*LIBL
*CURLIB
name
All libraries in the threadʹs library list are searched. Use the current library for the job. If no library is specified as the current library for the job, QGPL is used. Specify the name of the library. Examples
Example 1:
CHKXL1AUT
This command executes Excel‐eratorʹs authorization verification function to determine whether and how the product is authorized for use. Example 2:
CHKXL1AUT
MSGQ(QSYSOPR)
This command executes Excel‐eratorʹs authorization verification function to determine whether and how the product is authorized for use. If the product is not permanently authorized for use, a failure message is sent to the system operatorʹs message queue. Error messages
*ESCAPE messages
AUT9901
AUT9905
AUT9907
AUT9916
AUT9918
AUT9921
AUT9926
AUT9930
Weʹre sorry, the Excel‐erator demonstration period is over. Unable to access machine information. Excel‐erator processor group change grace period has expired. Excel‐erator release upgrade grace period has expired. Weʹre sorry, more than 30 days have elapsed since the Excel‐erator was first installed. Excel‐erator unpartitioned system grace period has expired. Excel‐erator processor limit exceeded grace period has expired. Excel‐erator authorization check failed. Chapter 7 Commands
59
60
Excel-erator Programmer's Guide and Reference
Copy To Excel (CPYTOEXCEL)
Where allowed to run: All environments (*ALL) Threadsafe: No The Copy To Excel (CPYTOEXCEL) command converts one or more IBM i database files into an Excel spreadsheet which is stored in IBM iʹs Integrated File System. Parameters
Keyword Description Choices Notes FROMFILE From file Qualified object name Qualifier 1: From file Name Required, Positional 1 Qualifier 2: Library Name, *LIBL, *CURLIB TOOBJ Object Character value, *FILE, *FILELIB, *TRNEXT, *MBR, *TEXT, *MBRCDAT, *MBRCCYY, *MBRCYY, *MBRCMM, *MBRCDD, *MBRCTIM, *MBRGDAT, *MBRGCYY, *MBRGYY, *MBRGMM, *MBRGDD, *MBRGTIM Required, Positional 2 FROMMBR From member Name, *FIRST, *LAST Optional, Positional 3 COLHDG Column headings *FLDNAM, *FLDNAMBLD, *ALIAS, *ALIASBLD, *COLHDG, Optional, *COLHDGBLD, *COLHD1, *COLHD1BLD, *COLTXT, Positional 4 *COLTXTBLD, *NONE, *TXT, *TXTBLD, *TXTCOL, *TXTCOLBLD FIELD Field Single values: *ALL Other values (up to 256 repetitions): Name Optional TRANSFORM Transform *BIFF8, *CSVUTF8, *CSVUTF8M, *CSVRFC, *CSVRFCQ, *BIFF4, *XMLSS, *OOXML Optional SHEETNAME Sheet name Character value, *FILE, *FILELIB, *MBR, *TEXT, *MBRCDAT, *MBRCCYY, *MBRCYY, *MBRCMM, *MBRCDD, *MBRCTIM, *MBRGDAT, *MBRGCYY, *MBRGYY, *MBRGMM, *MBRGDD, *MBRGTIM Optional SHEETTITLE Sheet title Single values: *NONE Other values (up to 5 repetitions): Character value Optional ADDWS Add worksheet Single values: *NONE Other values (up to 63 repetitions): Element list Optional Element 1: From file Qualified object name Qualifier 1: From file Name Qualifier 2: Library Name, *LIBL, *CURLIB Element 2: From member Name, *FIRST, *LAST Element 3: Field Single values: *ALL Other values (up to 256 repetitions): Name Element 4: Sheet name Character value, *FILE, *FILELIB, *MBR, *TEXT, *MBRCDAT, *MBRCCYY, *MBRCYY, *MBRCMM, *MBRCDD, *MBRCTIM, *MBRGDAT, *MBRGCYY, *MBRGYY, *MBRGMM, *MBRGDD, *MBRGTIM Element 5: Sheet title Single values: *NONE Other values (up to 5 repetitions): Character value PRTHEADER Print header Character value, *RCDTEXT, *MBRTEXT, *FILTEXT, *NONE PRTFOOTER Print footer Character value, *RCDTEXT, *MBRTEXT, *FILTEXT, *NONE Optional FONT Font typeface Character value, *ARIAL, *COURIER Optional COMMENT Cell comments Single values: *NONE Other values (up to 32 repetitions): Element list Optional Element 1: Column 1‐256, A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, AA, AB, AC, AD, AE, AF, AG, AH, AI, AJ, AK, AL, AM, AN, AO, AP, AQ, AR, AS, AT, AU, AV, AW, AX, AY, AZ, BA, BB, BC, BD, BE, BF, BG, BH, BI, BJ, BK, BL, BM, BN, BO, BP, BQ, BR, BS, BT, BU, BV, BW, BX, BY, BZ, CA, CB, CC, CD, CE, CF, CG, CH, CI, CJ, CK, CL, CM, CN, CO, CP, CQ, CR, CS, CT, CU, CV, CW, CX, CY, Chapter 7 Commands
Optional 61
CZ, DA, DB, DC, DD, DE, DF, DG, DH, DI, DJ, DK, DL, DM, DN, DO, DP, DQ, DR, DS, DT, DU, DV, DW, DX, DY, DZ, EA, EB, EC, ED, EE, EF, EG, EH, EI, EJ, EK, EL, EM, EN, EO, EP, EQ, ER, ES, ET, EU, EV, EW, EX, EY, EZ, FA, FB, FC, FD, FE, FF, FG, FH, FI, FJ, FK, FL, FM, FN, FO, FP, FQ, FR, FS, FT, FU, FV, FW, FX, FY, FZ, GA, GB, GC, GD, GE, GF, GG, GH, GI, GJ, GK, GL, GM, GN, GO, GP, GQ, GR, GS, GT, GU, GV, GW, GX, GY, GZ, HA, HB, HC, HD, HE, HF, HG, HH, HI, HJ, HK, HL, HM, HN, HO, HP, HQ, HR, HS, HT, HU, HV, HW, HX, HY, HZ, IA, IB, IC, ID, IE, IF, IG, IH, II, IJ, IK, IL, IM, IN, IO, IP, IQ, IR, IS, IT, IU, IV Element 2: Row 1‐65536, 1 Element 3: Text Character value REPLACE Replace stream file data *NO, *YES, Y, N Optional DTAAUT Data authorities *ALL, *NONE, *RWX, *RX, *RW, *WX, *R, *W, *X, *EXCLUDE, *INHERIT Optional CRTDIR Create directories *NO, *YES, Y, N Optional OWNER Owner Name, *CURUSRPRF Optional OBJATR Object attribute Single values: *NONE Other values (up to 2 repetitions): Element list Optional FILESHARE COLHDGFMT Element 1: Attribute *DISKSTGOPT Element 2: Value *NORMAL, *MINIMIZE, *DYNAMIC File sharing Element list Element 1: Password to open Character value Element 2: Password to modify Character value Element 3: Read‐only recommended *NO, *YES, N, Y Column heading format Single values: *DEFAULT Other values: Element list Optional Optional Element 1: Alignment‐Horizontal *GENERAL, *TYPE, *LEFT, *CENTER, *RIGHT, *FILL, *JUSTIFY, *CENTERSEL, 0, 1, 2, 3, 4, 5, 6, 8 Element 2: Border‐Top line style *NONE, *THIN, *MEDIUM, *DASHED, *DOTTED, *THICK, *DOUBLE, *HAIR, 0, 1, 2, 3, 4, 5, 6, 7 Element 3: Border‐Left line style *NONE, *THIN, *MEDIUM, *DASHED, *DOTTED, *THICK, *DOUBLE, *HAIR, 0, 1, 2, 3, 4, 5, 6, 7 Element 4: Border‐Bottom line style *NONE, *THIN, *MEDIUM, *DASHED, *DOTTED, *THICK, *DOUBLE, *HAIR, 0, 1, 2, 3, 4, 5, 6, 7 Element 5: Border‐Right line style *NONE, *THIN, *MEDIUM, *DASHED, *DOTTED, *THICK, *DOUBLE, *HAIR, 0, 1, 2, 3, 4, 5, 6, 7 Element 6: Border‐Top line color *SYSTEM, *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 32767, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Element 7: Border‐Left line color *SYSTEM, *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 32767, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Element 8: Border‐Bottom line color 62
*SYSTEM, *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 32767, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Excel-erator Programmer's Guide and Reference
Element 9: Border‐Right line color *SYSTEM, *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 32767, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Element 10: Patterns‐Type *NONE, *SOLID, *GRAY75, *GRAY50, *GRAY25, *GRAY12, *GRAY6, *STRIPEH50, *STRIPEH25, *STRIPEV50, *STRIPEV25, *STRIPED50, *STRIPED25, *STRIPEDR50, *STRIPEDR25, *HATCHD75, *HATCHD50, *HATCHD38, *HATCHH38, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18 Element 11: Patterns‐Foreground *AUTOMATIC, *BLACK, *WHITE, *RED, *BRIGHTGREEN, color *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 24, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Element 12: Patterns‐Background *AUTOMATIC, *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, color *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 25, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 PALETTE Element 13: Protection‐Locked *YES, *NO, 0, 1 Color palette Values (up to 16 repetitions): Element list Element 1: Color to replace *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50 Element 2: Red component 0‐255 Optional Element 3: Green component 0‐255 Element 4: Blue component 0‐255 CSVSEPCHR CSV separator character Character value, *COMMA, *PERIOD, *PIPE, *SEMICOLON, *SLASH, *TAB Optional PAGESETUP Page setup Single values: *NONE Other values: Element list Optional Element 1: Paper size *LETTER, *LEGAL, *STATEMENT, *EXECUTIVE, *LEDGER, *A3, *A4, *A5, *B4, *B5, 1, 4, 5, 6, 7, 8, 9, 11, 12, 13 Element 2: Orientation *PORTRAIT, *LANDSCAPE, 0, 1 Element 3: Scale to % normal size 10‐400, *AUTO Element 4: Scale to page(s) wide 1‐32767, *AUTO Element 5: Scale to page(s) tall 1‐32767, *AUTO Element 6: Print gridlines *NO, *YES, 0, 1 Element 7: Print black and white *NO, *YES, 0, 1 Element 8: Print draft quality *NO, *YES, 0, 1 Element 9: Print row and column *NO, *YES, 0, 1 headings FREEZEPANE SHEETOPT TRGCCSID Element 10: Print comments *NONE, *DSP, *END, 0, 2, 3 Element 11: Print order *DOWN, *OVER, 0, 1 Freeze pane Single values: *NO Other values: Element list Element 1: Rows to freeze *CALC, *NONE, ‐2 Element 2: Columns to freeze Integer, *NONE Sheet option Element list Element 1: Right to left *CONTEXT, *NO, *YES, 0, 1, 2 Target coded character set id 1‐65533, 1252 Chapter 7 Commands
Optional Optional Optional 63
SRCCCSID Source coded character set id 1‐65533, *KBDTYPE, *SYSVAL, *JOBDFT Optional From file (FROMFILE)
Specifies the database file to copy. CHAR(10), CHAR(10). This is a required parameter. Qualifier 1: From file
name
Specify the name of the file. Qualifier 2: Library
*LIBL
*CURLIB
name
All libraries in the threadʹs library list are searched. Use the current library for the job. If no library is specified as the current library for the job, QGPL is used. Specify the name of the library. Object (TOOBJ)
Specifies the path name of the object (stream file) to create. For more information on specifying path names, see Programming > Control language > CL concepts > IBM i objects > Object naming rules topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. CHAR(5000) This is a required parameter. path-name
Specify up to 5000 characters of path name. For example, to create a file with name abc.txt in a directory with name /MyDirectory, specify ʹ/MyDirectory/abc.txtʹ Excel‐erator provides several special values that can used to construct dynamic object (stream file) names. When the special values are found, the associated data is blank trimmed and substituted into the path specified when it is processed. If the data associated with a special value is blank, ʹBLANKʹ is substituted. If the data associated with a special value contains characters not allowed in an object name, question marks (ʹ?ʹ) for example, the name will be invalid and the command will fail. The special values must be delimited by an underscore (ʹ_ʹ) a period (ʹ.ʹ) a slash (ʹ/ʹ or ʹ\ʹ) a dash (ʹ‐ʹ) or another special value (which starts with ʹ*ʹ). The transform related special values are: *TRNEXT
Transform dependent file extension CHAR(3) or CHAR(4).  XLS for *BIFF8 or *BIFF4.  csv for *CSVUTF8, *CSVUTF8M, *CSVRFC, or *CSVRFCQ  xml for *XMLSS.  xlsx for *OOXML. The member related special values are: *FILE
*FILELIB
*MBR
*TEXT
*MBRCDAT
*MBRCCYY
*MBRCYY
*MBRCMM
*MBRCDD
*MBRCTIM
64
File name CHAR(10). Library containing the file CHAR(10). Member name CHAR(10). Member Text ʹdescriptionʹ CHAR(50). Date the member was created CHAR(7) CYYMMDD. CYY portion of *MBRCDAT CHAR(3). YY portion of *MBRCDAT CHAR(2). MM portion of *MBRCDAT CHAR(2). DD portion of *MBRCDAT CHAR(2). Time the member was created CHAR(6) HHMMSS. Excel-erator Programmer's Guide and Reference
*MBRGDAT
*MBRGCYY
*MBRGYY
*MBRGMM
*MBRGDD
*MBRGTIM
Date the member was changed CHAR(7) CYYMMDD. CYY portion of *MBRGDAT CHAR(3). YY portion of *MBRGDAT CHAR(2). MM portion of *MBRGDAT CHAR(2). DD portion of *MBRGDAT CHAR(2). Time the member was changed CHAR(6) HHMMSS. From member (FROMBR)
Specifies the name of the member to copy. CHAR(10). *FIRST
*LAST
name
The first member in the database from‐file is processed. The last member in the database from‐file is processed. Specify the name of the database from‐file member to process. Column headings (COLHDG)
Specifies the column headings generated. CHAR(10) *FLDNAM
*FLDNAMBLD
*ALIAS
*ALIASBLD
*COLHDG
*COLHDGBLD
*COLHD1
*COLHD1BLD
*COLTXT
*COLTXTBLD
*NONE
*TXT
*TXTBLD
*TXTCOL
*TXTCOLBLD
The fileʹs field names are used as column headings. The fileʹs field names are used as column headings. The column headings are bold. The fileʹs field aliases are used as column headings. The fileʹs field aliases are used as column headings. The column headings are bold. The fileʹs field column headings are used as column headings. The fileʹs field column headings are used as column headings. The column headings are bold. The fileʹs field column headings are used as column headings. A heading with multiple lines is text wrapped into a single cell. The fileʹs field column headings are used as column headings. A heading with multiple lines is text wrapped into a single cell. The column headings are bold. The fileʹs field column headings are used as column headings. A heading with multiple lines is text wrapped into a single cell. If the column headings are blank, the field text is used. The fileʹs field column headings are used as column headings. A heading with multiple lines is text wrapped into a single cell. If the column headings are blank, the field text is used. The column headings are bold. No column headings are included. The fileʹs field texts are used as column headings. The fileʹs field texts are used as column headings. The column headings are bold. The fileʹs field texts are used as column headings. If the field text is blank the field column heading are used. A heading with multiple lines is text wrapped into a single cell. The fileʹs field texts are used as column headings. If the field text is blank the field column heading are used. A heading with multiple lines is text wrapped into a single cell. The column headings are bold. Field (FIELD)
Specifies the list of fields to include in the spreadsheet. CHAR(10) Single values
*ALL
All fields in the database file are included in the spreadsheet in the order they appear in the file. Other values (up to 256 repetitions)
name
Specify the list of field names to be included in the spreadsheet. The fields appear in the spreadsheet in the order specified, duplicates are allowed. Transform (TRANSFORM)
Specifies the target format to which the data is transformed. CHAR(10). *BIFF8
Microsoftʹs Binary Interchange File Format Version 8, the format used by Excel version 8.0 (Excel 97/98), Chapter 7 Commands
65
*CSVUTF8
*CSVUTF8M
*CSVRFC
*CSVRFCQ
*XMLSS
*OOXML
*BIFF4
Excel 9.0 (Excel 2000/2001), Excel 10.0 (Excel XP/v.X) and Excel 11.0 (Excel 2003/2004). Comma Separated Values (CSV) format. Data is converted to UTF‐8. Trailing blanks are trimmed. Comma Separated Values (CSV) format. Data is converted to UTF‐8 and Byte Order Mark xEFBBBF is inserted at the start of the file. Trailing blanks are trimmed. Comma Separated Values (CSV) format. Data is converted to US‐ASCII in strict compliance with RFC4180 Common Format and MIME Type for Comma‐Separated Values (CSV) Files. Quoting is avoided unless need data containing quotes. Trailing blanks are trimmed. Comma Separated Values (CSV) format. Data is converted to US‐ASCII in strict compliance with RFC4180 DOUBLE QUOTED Common Format and MIME Type for Comma‐Separated Values (CSV) Files. Character data is always quoted. Trailing blanks are trimmed. Microsoftʹs Excel specific ʺXML Spreadsheet formatʺ introduced with Excel 2002 and Excel 2003. Office Open XML developed by Microsoft. Excel‐erator implements the ISO/IEC 29500:2008 Strict specification, suitable for use with Excel 2010 and suitable for use with Excel 2007 if dates are not present in the spreadsheet. See http://en.wikipedia.org/wiki/Office_Open_XML for additional information. Microsoftʹs Binary Interchange File Format Version 4, the format used by Excel version 4.0 (Excel 4.0). Note: Use *BIFF8 instead of *BIFF4. *BIFF4 is included for compatibility with existing software and is no longer being enhanced. Sheet name (SHEETNAME)
Specifies the name of the worksheet. CHAR(32) *MBR
character-value
The member name is the sheet name. Specify up to 32 characters enclosed in apostrophes. Excel‐erator provides several special values that can used to construct dynamic sheet names. When the special values are found, the associated data is blank trimmed and substituted into the name specified when it is processed. If the data associated with a special value is blank, ʹBLANKʹ is substituted. The special values must be delimited by an underscore (_) a period (ʹ.ʹ) or another special value (which starts with ʹ*ʹ). The result is trimmed if the length is exceeded. *FILE
*FILELIB
*MBR
*TEXT
*MBRCDAT
*MBRCCYY
*MBRCYY
*MBRCMM
*MBRCDD
*MBRCTIM
*MBRGDAT
*MBRGCYY
*MBRGYY
*MBRGMM
*MBRGDD
*MBRGTIM
File name CHAR(10). Library containing the file CHAR(10). Member name CHAR(10). Member Text ʹdescriptionʹ CHAR(50). Date the member was created CHAR(7) CYYMMDD. CYY portion of *MBRCDAT CHAR(3). YY portion of *MBRCDAT CHAR(2). MM portion of *MBRCDAT CHAR(2). DD portion of *MBRCDAT CHAR(2). Time the member was created CHAR(6) HHMMSS. Date the member was changed CHAR(7) CYYMMDD. CYY portion of *MBRGDAT CHAR(3). YY portion of *MBRGDAT CHAR(2). MM portion of *MBRGDAT CHAR(2). DD portion of *MBRGDAT CHAR(2). Time the member was changed CHAR(6) HHMMSS. Sheet title (SHEETTITLE)
Specifies the title of the worksheet. CHAR(80) Note: When prompting, the input field can be expanded by typing an ampersand (&) in the first position of the field followed by a blank, and pressing enter. 66
Excel-erator Programmer's Guide and Reference
Single values
*NONE
Title lines are not included in the sheet. Other values (up to 5 repetitions)
character-value
Specify up to 80 characters enclosed in apostrophes. Add worksheet (ADDWS)
Specifies one or more worksheets to add to the generated spreadsheet by specifying the database file, member name, and list of fields used as source to add. CHAR(10), CHAR(10), CHAR(10) CHAR(10) This is a required parameter. Single values
*NONE
No additional worksheets are included. Element 1: From file
The name and library of a database file. Qualifier 1: From file name
Qualifier 2: Library
*LIBL
*CURLIB
name
Specify the name of the file. All libraries in the threadʹs library list are searched. Use the current library for the job. If no library is specified as the current library for the job, QGPL is used. Specify the name of the library. Element 2: From member
*FIRST
*LAST
name
The first member in the database from‐file is processed. The last member in the database from‐file is processed. Specify the name of the database from‐file member to process. Element 3: Field
Single values
Other values
*ALL
name
All fields in the database file are included in the spreadsheet in the order they appear in the file. Specify the list of field names to be included in the spreadsheet. The fields appear in the spreadsheet in the order specified, duplicates are allowed. Element 5: Sheet name
Specifies the name of the worksheet. CHAR(32) *MBR
character-value
The member name is the sheet name. Specify up to 32 characters enclosed in apostrophes. Excel‐erator provides several special values that can used to construct dynamic sheet names. When the special values are found, the associated data is blank trimmed and substituted into the name specified when it is processed. If the data associated with a special value is blank, ʹBLANKʹ is substituted. The special values must be delimited by an underscore (_) a period (ʹ.ʹ) or another special value (which starts with ʹ*ʹ). The result is trimmed if the length is exceeded. *FILE
*FILELIB
*MBR
*TEXT
*MBRCDAT
*MBRCCYY
*MBRCYY
*MBRCMM
*MBRCDD
*MBRCTIM
File name CHAR(10). Library containing the file CHAR(10). Member name CHAR(10). Member Text ʹdescriptionʹ CHAR(50). Date the member was created CHAR(7) CYYMMDD. CYY portion of *MBRCDAT CHAR(3). YY portion of *MBRCDAT CHAR(2). MM portion of *MBRCDAT CHAR(2). DD portion of *MBRCDAT CHAR(2). Time the member was created CHAR(6) HHMMSS. Chapter 7 Commands
67
*MBRGDAT
*MBRGCYY
*MBRGYY
*MBRGMM
*MBRGDD
*MBRGTIM
Date the member was changed CHAR(7) CYYMMDD. CYY portion of *MBRGDAT CHAR(3). YY portion of *MBRGDAT CHAR(2). MM portion of *MBRGDAT CHAR(2). DD portion of *MBRGDAT CHAR(2). Time the member was changed CHAR(6) HHMMSS. Element 6: Sheet title
Specifies the title of the worksheet. CHAR(80) Note: When prompting, the input field can be expanded by typing an ampersand (&) in the first position of the field followed by a blank, and pressing enter. Single values
Other values
Title lines are not included in the sheet. *NONE
character-value
Specify up to 80 characters enclosed in apostrophes. Print header (PRTHEADER)
Specifies the print header placed in the spreadsheet. CHAR(50) *NONE
*RCDTEXT
*MBRTEXT
*FILTEXT
character-value
No print header is included in the file. The record text is used as the print header. The member text is used as the print header. The file text is used as the print header. Enter the value to use as the print header. The header text can include the standard Excel codes: &A
Inserts the worksheet name &B
Toggles bold &C
Start of centered section &D
Inserts the current date &E
Toggles double‐underline &F
Inserts the workbook name &I
Toggles italic &L
Start of left section &N
Inserts the total page count &R
Start of right section &S
Toggles strikethrough &T
Inserts the current time &[Tab]
Inserts the worksheet name &U
Toggles underline &X
Toggles superscript &Y
Toggles subscript &P
Inserts the current page number &P+n
Inserts the page number incremented by n &P-n
Inserts the page number decremented by n &[Path]
Inserts the workbook path &&
Escapes the ampersand character &"fontname" Selects the named font Selects the specified 2‐digit font point size &nn
Print footer (PRTFOOTER)
Specifies the print footer placed in the spreadsheet. CHAR(50) *NONE
*RCDTEXT
*MBRTEXT
*FILTEXT
character-value
68
No print footer is included in the file. The record text is used as the print footer. The member text is used as the print footer. The file text is used as the print footer. Enter the value to use as the print footer. The footer text can include the standard Excel codes: Excel-erator Programmer's Guide and Reference
&A
&B
&C
&D
&E
&F
&I
&L
&N
&R
&S
&T
&[Tab]
&U
&X
&Y
&P
&P+n
&P-n
&[Path]
&&
&"fontname"
&nn
Inserts the worksheet name Toggles bold Start of centered section Inserts the current date Toggles double‐underline Inserts the workbook name Toggles italic Start of left section Inserts the total page count Start of right section Toggles strikethrough Inserts the current time Inserts the worksheet name Toggles underline Toggles superscript Toggles subscript Inserts the current page number Inserts the page number incremented by n Inserts the page number decremented by n Inserts the workbook path Escapes the ampersand character Selects the named font Selects the specified 2‐digit font point size Font typeface (FONT)
Specifies the font name placed into the file. The font specified must be available on the PC that is running Excel. CHAR(32). *ARIAL
*COURIER
character-value
Font Arial is used. Font Courier New, a fixed pitch font, is used. The name of the font to use. Cell comments (COMMENT)
Specifies cell comments, consisting of a cellʹs coordinate column/row and the comment text, which are added to the generated spreadsheet. A comment can be added to a cell even if it does not contain data. INT(4) (where A=1, B=2, etc.), INT(4) CHAR(2048) Single values
*NONE
No comments are added to the spreadsheet. Element 1: Column
1-256
The column of the cell that receives the comment. You can use either a letter or number designation. Element 2: Row
1-65536
The row of the cell that receives the comment. Element 3: Text
character-value
Enter the text that is to appear in the comment. Replace stream file data (REPLACE)
Specifies whether data in the stream file should be replaced if the object already exists. If the object does not exist, it is created. CHAR(1) *YES
*NO
Data in an existing object is replaced. Data in an existing object is not replaced and an error is generated. Chapter 7 Commands
69
Data authorities (DTAAUT)
Specifies the *PUBLIC data authorities assign to the created stream file. CHAR(10) *ALL
*NONE
*RWX
*RX
*RW
*WX
*R
*W
*X
*EXCLUDE
*INHERIT
The *PUBLIC is given *RWX authority to perform all operations on the object except those limited to the owner or controlled by object existence, object management, object alter, and object reference authority. The *PUBLIC can change the object and perform basic functions on the object. *RWX authority provides object operational authority and all the data authorities. The *PUBLIC does not have any of the data authorities to the object. The *PUBLIC is given *RWX authority to perform all operations on the object except those limited to the owner or controlled by object existence, object management, object alter, and object reference authority. The *PUBLIC can change the object and perform basic functions on the object. *RWX authority provides object operational authority and all the data authorities. The *PUBLIC is given *RX authority to perform basic operations on the object, such as run a program or display the contents of a file. The user is prevented from changing the object. *RX authority provides object operational authority and read and execute authorities. The *PUBLIC is given *RW authority to view the contents of an object and change the contents of an object. *RW authority provides object operational authority and data read, add, update, and delete authorities. The *PUBLIC is given *WX authority to change the contents of an object and run a program or search a library or directory. *WX authority provides object operational authority and data add, update, delete, and execute authorities. The *PUBLIC is given *R authority to view the contents of an object. *R authority provides object operational authority and data read authority. The *PUBLIC is given *W authority to change the contents of an object. *W authority provides object operational authority and data add, update, and delete authorities. The *PUBLIC is given *X authority to run a program or search a library or directory. *X authority provides object operational authority and data execute authority. Exclude authority prevents the *PUBLIC from accessing the object. The *PUBLIC and other authorities to the object are copied as follows. The owner, primary group, and public data and object authorities (*R, *W, *X, *OBJEXIST, *OBJMGT, *OBJALTER, and *OBJREF) are copied from the parent directoryʹs owner, primary group, and public data and object authorities. In addition, the private authorities (if any) and authorization list (if any) are copied from the parent directory. If the new file has a different owner than the parent directory and the new fileʹs owner has a private authority in the parent directory, that private authority is not copied from the parent directory. The authority for the owner of the new file is copied from the owner of the parent directory. Create directories (CRTDIR)
Specifies whether directories in the object name should be created if they do not exist. CHAR(1) *NO
*YES
Directories are not created. Directories are created. Owner (OWNER)
Specifies the user profile that is the owner of the newly created object. CHAR(10) *CURUSRPRF
name
70
The object is owned by the current effective user of the current job or thread. Specify the user profile that is the owner of the newly created object. If the current effective user does not have *ADD data authority to the user profile, or if the profile does not exist, ownership of the object is determined in the same manner as *CURUSRPRF. Excel-erator Programmer's Guide and Reference
Object attribute (OBJATR)
Specifies additional attributes for the generated file and is similar in function to the CHGATR command. Each attribute is specified as an attribute/value pair. If an attribute is specified more than once, the last one wins. INT(4) INT(4) *NONE
*DISKSTGOPT
No additional attributes are specified. Determines how auxiliary storage is allocated by the system for the object. This attribute can only be specified for byte stream files in the Root (/), QOpenSys and User‐defined file systems. This attribute will be ignored for *TYPE1 byte stream files. Valid values are: *NORMAL
The auxiliary storage will be allocated normally. That is, as additional auxiliary storage is required, it will be allocated in logically sized extents to accommodate the current space requirement, and anticipated future requirements, while minimizing the number of disk I/O operations. If the *DISKSTGOPT attribute has not been specified for an object, this value is the default. *MINIMIZE
The auxiliary storage will be allocated to minimize the space used by the object. That is, as additional auxiliary storage is required, it will be allocated in small sized extents to accommodate the current space requirement. Accessing an object composed of many small extents may increase the number of disk I/O operations for that object. *DYNAMIC
The system will dynamically determine the optimum auxiliary storage allocation for the object, balancing space used versus disk I/O operations. For example, if a file has many small extents, yet is frequently being read and written, then future auxiliary storage allocations will be larger extents to minimize the number of disk I/O operations. Or, if a file is frequently truncated, then future auxiliary storage allocations will be small extents to minimize the space used. Additionally, information will be maintained on the byte stream file sizes for this system and its activity. This file size information will also be used to help determine the optimum auxiliary storage allocations for this object as it relates to the other objects sizes. File sharing (FILESHARE)
Specifies how the generated spreadsheet is secured. Each element corresponds to an Excel setting accessible from the ʺSave Asʺ dialog. The limitations, and resulting encryption strength vary significantly between *BIFF8 and *BIFF4 and are documented separately. For *BIFF8
Element 1: Password to open
character-value
Specifies the case sensitive password required to open and decrypt the file. If a password is not specified, the file is not encrypted and can be opened by anyone. CHAR(15) Any character, including DBCS, can be included in the password. The spreadsheet is encrypted using the RC4 algorithm. Element 2: Password to modify
character-value
Specifies the case sensitive password required to update the file. If a password is specified and someone changes the file without the password, that person can save the file only by giving it a different name. If a password is not specified, the file can be updated by anyone. This password does not cause the file to be encrypted. CHAR(15) Excel‐erator restricts this password to a‐z, A‐Z, 0‐9, the space character and symbols !ʺ#$%&ʹ()*+,‐
./:;<=>?@[\]^_`{|}~. That is the ascii code points from x20‐x7E which map directly to UTF8 and the base plane of unicode. With this restriction, the password can be typed by virtually any recipient, without knowing the details of their keyboard or code page of their machine. Note: The security of Password to modify is notoriously weak. Chapter 7 Commands
71
Element 3: Read-only recommended
*NO
*YES
No recommendation given. CHAR(1) value ʹNʹ. Specifies that users get a read‐only (read‐only: A setting that allows a file to be read or copied but not changed or saved.) recommendation when they open the file. This does not prevent users from opening the file as read‐write so that they can edit and save changes. CHAR(1) value ʹYʹ. For *BIFF4
*BIFF4 security is notoriously insecure and may not be suitable for all environments. Password crackers are freely available. While not a requirement, for best results use a password that contains only characters a‐z, A‐Z, 0‐9, the space character and symbols !ʺ#$%&ʹ()*+,‐./:;<=>?@[\]^_`{|}~. This insures compatibility with Excel Macintosh edition, for example. Element 1: Password to open
character-value
Specifies the case sensitive password required to open and decrypt the file. If a password is not specified, the file is not encrypted and can be opened by anyone. CHAR(15) Element 2: Password to modify
character-value
Specifies the case sensitive password required to update the file. If a password is specified and someone changes the file without the password, that person can save the file only by giving it a different name. If a password is not specified, the file can be updated by anyone. This password does not cause the file to be encrypted. CHAR(15) Element 3: Read-only recommended
*NO
*YES
No recommendation given. CHAR(1) value ʹNʹ. Specifies that users get a read‐only (read‐only: A setting that allows a file to be read or copied but not changed or saved.) recommendation when they open the file. This does not prevent users from opening the file as read‐write so that they can edit and save changes. CHAR(1) value ʹYʹ. Column heading format (COLHDGFMT)
Specifies formatting applied to the cells containing column headings. Each element corresponds to an Excel setting accessible by selecting Format > Cells. The values that each element accepts have their usual Excel meanings with one exception: ʺAlignment‐Horizontalʺ accepts a *TYPE special value, which is not available in Excel. When *TYPE is specified, the column headings of character fields are given *LEFT horizontal alignment while the column headings of numeric fields are given *RIGHT horizontal alignment. See Excelʹs help for additional information. Each element is INT(2). Single values
*DEFAULT
Default values are used. Element 1: Alignment-Horizontal
Specifies alignment of text within cells. *GENERAL
*TYPE
*LEFT
*CENTER
*RIGHT
*FILL
*JUSTIFY
*CENTERSEL
Cells are given Excelʹs ʺGeneralʺ alignment. Alignment is determined by the fieldʹs data type: right for numeric fields, left for character fields. Cells are given Excelʹs ʺLeftʺ alignment. Cells are given Excelʹs ʺCenterʺ alignment. Cells are given Excelʹs ʺRightʺ alignment. Cells are given Excelʹs ʺFillʺ alignment. Cells are given Excelʹs ʺJustifyʺ alignment. Cells are given Excelʹs ʺCenter Across Selectionʺ alignment. Element 2-5: Border-Line styles.
Specify the Top/Left/Bottom/Right border line styles. 72
Excel-erator Programmer's Guide and Reference
*NONE
*THIN
*MEDIUM
*DASHED
*DOTTED
*THICK
*DOUBLE
*HAIR
Line is removed. Line is thin. Line is medium. Line is dashed. Line is dotted. Line is thick. Line is doubled. Line is hair. Element 6-9: Border-Line colors.
Specify the Top/Left/Bottom/Right border line colors. *SYSTEM
*BLACK
*WHITE
*RED
*BRIGHTGREEN
*BLUE
*YELLOW
*PINK
*TURQUOISE
*DARKRED
*GREEN
*DARKBLUE
*DARKYELLOW
*VIOLET
*TEAL
*GRAY25
*GRAY50
System default color. Same as *COLOR1. Red=0, Green=0, Blue=0 Same as *COLOR2. Red=255, Green=255, Blue=255 Same as *COLOR3. Red=255, Green=0, Blue=0 Same as *COLOR4. Red=0, Green=255, Blue=0 Same as *COLOR5. Red=0, Green=0, Blue=255 Same as *COLOR6. Red=255, Green=255, Blue=0 Same as *COLOR7. Red=255, Green=0, Blue=255 Same as *COLOR8. Red=0, Green=255, Blue=255 Same as *COLOR9. Red=128, Green=0, Blue=0 Same as *COLOR10. Red=0, Green=128, Blue=0 Same as *COLOR11. Red=0, Green=0, Blue=128 Same as *COLOR12. Red=128, Green=128, Blue=0 Same as *COLOR13. Red=128, Green=0, Blue=128 Same as *COLOR14. Red=0, Green=128, Blue=128 Same as *COLOR15. Red=192, Green=192, Blue=192 Same as *COLOR16. Red=128, Green=128, Blue=128 Element 10: Patterns-Type
Specifies the pattern to apply. *NONE
*SOLID
*GRAY75
*GRAY50
*GRAY25
*GRAY12
*GRAY6
*STRIPEH50
*STRIPEH25
*STRIPEV50
*STRIPEV25
*STRIPED50
*STRIPED25
*STRIPEDR50
*STRIPEDR25
*HATCHD75
*HATCHD50
*HATCHD38
*HATCHH38
No pattern is used. Excelʹs ʺSolidʺ pattern. Excelʹs ʺ75% Grayʺ pattern. Excelʹs ʺ50% Grayʺ pattern. Excelʹs ʺ25% Grayʺ pattern. Excelʹs ʺ12.5% Grayʺ pattern. Excelʹs ʺ6.25% Grayʺ pattern. Excelʹs ʺHorizontal Stripeʺ pattern. Excelʹs ʺThin Horizontal Stripeʺ pattern. Excelʹs ʺVertical Stripeʺ pattern. Excelʹs ʺThin Vertical Stripeʺ pattern. Excelʹs ʺDiagonal Stripeʺ pattern. Excelʹs ʺThin Diagonal Stripeʺ pattern. Excelʹs ʺReverse Diagonal Stripeʺ pattern. Excelʹs ʺThin Reverse Diagonal Stripeʺ pattern. Excelʹs ʺThick Diagonal Crosshatchʺ pattern. Excelʹs ʺDiagonal Crosshatchʺ pattern. Excelʹs ʺThin Diagonal Crosshatchʺ pattern. Excelʹs ʺThin Horizontal Crosshatchʺ pattern. Element 11-12: Patterns-Colors
Specify the foreground and background pattern colors. *AUTOMATIC
System default color. Chapter 7 Commands
73
*BLACK
*WHITE
*RED
*BRIGHTGREEN
*BLUE
*YELLOW
*PINK
*TURQUOISE
*DARKRED
*GREEN
*DARKBLUE
*DARKYELLOW
*VIOLET
*TEAL
*GRAY25
*GRAY50
Same as *COLOR1. Red=0, Green=0, Blue=0 Same as *COLOR2. Red=255, Green=255, Blue=255 Same as *COLOR3. Red=255, Green=0, Blue=0 Same as *COLOR4. Red=0, Green=255, Blue=0 Same as *COLOR5. Red=0, Green=0, Blue=255 Same as *COLOR6. Red=255, Green=255, Blue=0 Same as *COLOR7. Red=255, Green=0, Blue=255 Same as *COLOR8. Red=0, Green=255, Blue=255 Same as *COLOR9. Red=128, Green=0, Blue=0 Same as *COLOR10. Red=0, Green=128, Blue=0 Same as *COLOR11. Red=0, Green=0, Blue=128 Same as *COLOR12. Red=128, Green=128, Blue=0 Same as *COLOR13. Red=128, Green=0, Blue=128 Same as *COLOR14. Red=0, Green=128, Blue=128 Same as *COLOR15. Red=192, Green=192, Blue=192 Same as *COLOR16. Red=128, Green=128, Blue=128 Element 13: Protection-Locked
Specifies if the cells are locked. Locking cells or hiding formulas has no effect unless the worksheet is protected. *YES
*NO
Cells are locked. Cells are not locked. Color palette (PALETTE)
Specifies replacements for the default colors included in the spreadsheetʹs palette. The color palette is made up of the specification for sixteen colors, numbered 1 through 16, and assigned names such as *BLACK, *RED, etc. Each color in turn is made up of the specification for the amount of red, green, and blue (RGB) components that make up the color. The amount is a number between 0 and 255. The larger the amount, the more of the component present. You can determine the RGB values for a specific color using Excelʹs Tools > Options > Color > Custom tab. INT(2), INT(2), INT(2) repeated 16 times. You specify a replacement for a default color by specifying its name and the new RGB values to use. If a color is modified then all references to the colorʹs name, used in other parameters, are also modified. For example, if color *BLACK is changed to (255 106 0), color *BLACK becomes orange and all parameters that specify *BLACK will produce this orange. Element 1: Color to replace
color-name
Specify the name to modify, example *BLACK. Element 2: Red component
integer
Specify the red RGB component. Element 3: Green component
integer
Specify the green RGB component. Element 4: Blue component
integer
Specify the blue RGB component. CSV separator character (CSVSEPCHR)
Specifies the character used to separate fields in the generated file. CHAR(1). Note: This parameter is ignored for transforms except those that generate Comma Separated Value (CSV). *COMMA
*PERIOD
74
Values are separated by a ʹ,ʹ. Values are separated by a ʹ.ʹ. Excel-erator Programmer's Guide and Reference
*PIPE
*SEMICOLON
*SLASH
*TAB
character-value
Values are separated by a ʹ|ʹ. Values are separated by a ʹ;ʹ. Values are separated by a ʹ/ʹ. Values are separated by a horizontal tab. Specify the character. Page setup (PAGESETUP)
Specifies page set up information included in the spreadsheet. Single values
*NONE
No page set up information is included in the spreadsheet. Element 1: Paper size
Specifies the paper size to print. INT(2) *LETTER
*LEGAL
*STATEMENT
*EXECUTIVE
*LEDGER
*A3
*A4
*A5
*B4
*B5
Use letter paper with a page size of 8.5ʺ x 11ʺ. Use legal paper with a page size of 8.5ʺ x 14ʺ. Use statement paper with a page size of 5.5ʺ x 8.5ʺ. Use executive paper with a page size of 7.25ʺ x 10.5ʺ. Use ledger paper with a page size of 11ʺ x 17ʺ. Use A3 paper with a page size of 297 mm x 420 mm. Use A4 paper with a page size of 210 mm x 297 mm. Use A5 paper with a page size of 148 mm x 210 mm. Use B4 paper with a page size of 250 mm x 353 mm. Use B5 paper with a page size of 176 mm x 250 mm. Element 2: Orientation
Specifies the print orientation on the page. INT(2) *PORTRAIT
*LANDSCAPE
The page has portrait orientation, with the long side on the left and right and with the short side on the top and bottom. The page has landscape orientation, with the short side on the left and right and with the long side on the top and bottom. Element 3: Scale to % normal size
Specifies the percentage of normal size used to scale the print. INT(2) If Element 4: Scale to page(s) wide or Element 5: Scale to page(s) tall are specified, this elementʹs radio button is not selected. *AUTO
10-400
A percentage adjustment is not specified. Specify a percentage adjustment to normal size. Element 4: Scale to page(s) wide
Specifies scaling in number of pages wide. INT(2) *AUTO
1-32767
Scale to pages is not specified. Specify the number of pages wide the spreadsheet is scaled to. Element 5: Scale to page(s) tall
Specifies scaling in number of pages tall. INT(2) *AUTO
1-32767
Scale to pages is not specified. Specify the number of pages tall the spreadsheet is scaled to. Element 6: Print gridlines
Specifies if grid lines are printed. INT(2) *NO
*YES
Grid lines do not print. Grid lines are printed. Chapter 7 Commands
75
Element 7: Print black and white
Specifies if printing is black and white. INT(2) *NO
*YES
Print in color. Print in black and white. Element 8: Print draft quality
Specifies if printing is draft quality. INT(2) *NO
*YES
Print with default print quality. Print with draft quality. Element 9: Print row and column headings
Specifies if row and column headings are printed. INT(2) *NO
*YES
Headings do not print. Headings are printed. Element 10: Print comments
Specifies comment printing. INT(2) *NONE
*DSP
*END
Comments do not print. Comments are printed as displayed. Comments are printed at the end. Element 11: Print order
Specifies the order in which pages are printed. INT(2) *DOWN
*OVER
Pages are printed down the spreadsheet, then over. Pages are printed across the spreadsheet, then down. Freeze pane (FREEZEPANE)
Specifies the number of rows at the top of the sheet and the number of columns at the left of the sheet that are frozen and remain visible when scrolling in the sheet. Single values
*NO
No data is frozen on the sheet. Element 1: Rows to freeze
Specifies the number of rows to freeze at the top of the sheet. INT(2) *CALC
*NONE
The number of rows to freeze is calculated based on the number of column heading and title rows specified. No rows are frozen at the top of the sheet. Element 2: Columns to freeze
Specifies the number of columns to freeze at the left of the sheet. INT(2) *NONE
integer
No columns are frozen at the left of the sheet. The number of columns frozen. Sheet option (SHEETOPT)
Specifies sheet option information included in the spreadsheet. Note: Currently implemented for *OOXML only. 76
Excel-erator Programmer's Guide and Reference
Element 1: Right to left
Specifies right to left viewing direction. INT(2) *CONTEXT
*NO
*YES
Viewing direction is not specified in the worksheet and depends on the context (viewer). Viewing direction is left to right. Viewing direction is right to left. Target coded character set id (TRGCCSID)
Specifies the ASCII coded character set identifier (CCSID) that is used to map character data in the generated spreadsheet. INT(4) Note: Only *BIFF4 supports this value and it is ignored unless TRANSFORM(*BIFF4) is specified. 1252
integer
The default Windows coded character set identifier is used. Specify the coded character set identifier to use. Source coded character set id (SRCCCSID)
Specifies the coded character set identifier (CCSID) used to create the spreadsheet. INT(4) Note: Only *BIFF4 supports this value and it is ignored unless TRANSFORM(*BIFF4) is specified. *KBDTYPE
*SYSVAL
*JOBDFT
integer
The system determines the coded character set identifier value from the QKBDTYPE system value. The system determines the coded character set identifier value from the QCHRID system value. The system uses the current jobʹs default coded character set identifier. Specify the coded character set identifier to use. Examples
Example 1:
CPYTOEXCEL
FROMFILE(CUSTOMER) TOOBJ('/Excel/*FILE.XLS')
CRTDIR(*YES)
This command converts file ʺCUSTOMERʺ into an Excel spreadsheet with the name ʺCUSTOMER.XLSʺ. The spreadsheet is placed in the ʺExcelʺ directory, which is created if it does not exist. Example 2:
CPYTOEXCEL
FROMFILE(INVOICE)
TOOBJ('/QNTC/NT1/C/ardept/invoice.*MBRCDAT.xls')
This command converts file ʺINVOICEʺ into an Excel spreadsheet with the name ʺINVOICE.cyymmdd.XLSʺ (where the from memberʹs creation date is substituted for cyymmdd). The spreadsheet is placed on a Windows system with the name ʺNT1ʺ in subdirectory ʺardeptʺ of the ʺCʺ share. Error messages
Parameter dependencies
XL17003
XL17004
XL17005
XL17006
XL17007
XL17008
XL17009
XL17010
When ADDWS() is specified, TRANSFORM(*BIFF8/*XMLSS/*OOXML) must be specified. When SHEETNAME() is specified TRANSFORM(*BIFF8/*XMLSS/*OOXML) must be specified. When SHEETTITLE() is specified TRANSFORM(*BIFF8/*XMLSS/*OOXML) must be specified. When TRANSFORM(*BIFF4) is specified COLHDG(*COLHD1) and COLHDG(*COLHD1BLD) can not be specified. When PRTHEADER() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. When PRTFOOTER() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. When FONT() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. When COMMENT() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. Chapter 7 Commands
77
XL17011
XL17012
XL17014
XL17015
XL17016
SCV7001
SCV7002
XL17017
XL17018
When TRGCCSID() is specified TRANSFORM(*BIFF4) must be specified. When SRCCCSID() is specified TRANSFORM(*BIFF4) must be specified. When FILESHARE() is specified TRANSFORM(*BIFF8/*BIFF4) must be specified. When COLHDGFMT() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. When PALETTE() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. CSV Separator character ʹ,ʹ required with TRANSFORM(*CSVRFC). CSV Separator character ʹ,ʹ required with TRANSFORM(*CSVRFCQ). When PAGESETUP() is specified TRANSFORM(*BIFF8/*XMLSS/*OOXML) must be specified. When FREEZEPANE() is specified TRANSFORM(*BIFF8/*XMLSS/*OOXML) must be specified. *ESCAPE messages
XL12014
78
Unable to copy file /. Excel-erator Programmer's Guide and Reference
Display Mail Log (DSPMAILLOG)
Where allowed to run: All environments (*ALL) Threadsafe: No The Display Mail Log (DSPMAILLOG) command shows the system mail log (IBM i journal QZMF). The mail log contains information about the processing of mail. Note: Mail journaling must be turned on. To turn on mail journaling, specify JOURNAL(*YES) on the CHGSMTPA command. Only journal receivers in the current chain are searched. Parameters
Keyword Description Choices Notes PERIOD Time period Element list Optional, Positional 1 Element 1: Starting date and time Element list Element 1: Starting time Time, *AVAIL Element 2: Starting date Date, *CURRENT, *BEGIN Element 2: Ending date and time Element list OUTPUT Element 1: Ending time Time, *AVAIL Element 2: Ending date Date, *CURRENT, *END Output *, *PRINT Optional, Positional 2 Time period (PERIOD)
Specifies the period of time for which the logged message data is shown. This parameter contains two lists of two elements each. Element 1: Starting date and time
Element 1: Starting time One of the following specifies the starting time from which entries are shown. Entries created before this time on the Starting date are not shown. *AVAIL
All data that is available for the specified date is shown. time
Specify the start time from which data for the specified date is shown. The time is specified in 24‐hour format and can be specified with or without a time separator:  Without a time separator, specify a string of 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds.  With a time separator, specify a string of 5 or 8 digits where the time separator specified for your job is used to separate the hours, minutes, and seconds. If you enter this command from the command line, the string must be enclosed in apostrophes. If a time separator other than the separator specified for your job is used, this command will fail. Element 2: Starting date One of the following specifies the starting date from which entries are shown. Entries created before this date are not shown. *CURRENT The current date is used. *BEGIN
The data from the beginning of the log is shown. date
Specify the start date from which data is shown. The date must be specified in the job date format. Element 2: Ending date and time
Element 1: Ending time One of the following specifies the ending time to which entries are shown. Entries created after this time on the Ending date are not shown. *AVAIL
All data that is available for the specified date is shown. time
Specify the end time to which data for the specified date is shown. The time is Chapter 7 Commands
79
specified in 24‐hour format and can be specified with or without a time separator:  Without a time separator, specify a string of 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds.  With a time separator, specify a string of 5 or 8 digits where the time separator specified for your job is used to separate the hours, minutes, and seconds. If you enter this command from the command line, the string must be enclosed in apostrophes. If a time separator other than the separator specified for your job is used, this command will fail. Element 2: Ending date One of the following specifies the ending date to which entries are shown. Entries created after this date are not shown. *CURRENT
The current date is used. *END
The data to the end of the log is shown. date
Specify the end date to which data is shown. The date must be specified in the job date format. Output (OUTPUT)
Specifies where the output from the command is sent. CHAR(10) *
*PRINT
The output is displayed (if requested by an interactive job) or printed with the jobʹs spooled output (if requested by a batch job). The output is printed with the jobʹs spooled output. Examples
Example 1:
DSPMAILLOG
The mail log entries for today are displayed on the screen. Example 2:
DSPMAILLOG
PERIOD((*AVAIL *BEGIN) (*AVAIL *END))
OUTPUT(*PRINT)
All available mail log entries in the current journal receiver chain are printed. Error messages
*ESCAPE messages
MSU1074
MSU1076
MSU5151
80
Error encountered processing request. No data for requested time range. Mail journaling has not been turned on. Excel-erator Programmer's Guide and Reference
Restart/Purge Local Mail (INZLOCAL)
Where allowed to run: All environments (*ALL) Threadsafe: No The Restart/Purge Local Mail (INZLOCAL) command ends and restarts IBM i mail components. This may be required to clear problems or to make configuration changes immediately effective. Parameters
Keyword Description Choices Notes SMTP Restart SMTP server *YES, *NO, Y, N Optional, Positional 1 SMTPPURGE Clear SMTP during restart *NO, *YES, Y, N Optional, Positional 2 MSF Restart MSF server *YES, *NO, Y, N Optional, Positional 3 MSFPURGE Clear MSF during restart *NO, *YES, Y, N Optional, Positional 4 Restart SMTP server (SMTP)
Specifies the whether the SMTP server is restarted. *YES
*NO
The SMTP server is first ended then started. The command does not restart the SMTP server. Clear SMTP during restart (SMTPPURGE)
Specifies the whether the SMTP server is purged during the restart. Note: Clear means that all IBM i SMTP email will be deleted. If you are not sure, select *NO. *NO
*YES
Existing messages are not cleared. Existing messages are cleared. Restart MSF server (MSF)
Specifies the whether the MSF server is restarted. *YES
*NO
The MSF server is first ended then started. The command does not restart the MSF server. Clear MSF during restart (MSFPURGE)
Specifies the whether the MSF server is cleared during the restart. Note: Clear means that mail server framework distributions (emails) will be deleted from this system. If you are not sure, select *NO. *NO
*YES
The MSF is not cleared. The MSF is cleared. Examples
Example 1:
INZLOCAL
This command restarts the SMTP server and Mail Server Framework jobs. Chapter 7 Commands
81
Example 2:
INZLOCAL
SMTPPURGE(*YES) MSFPURGE(*YES)
This command restarts the SMTP server and Mail Server Framework jobs after purging all data they contain. Error messages
Parameter dependencies
MSU7012
MSU7013
82
SMTP cannot be cleared unless it is also restarted. MSF cannot be cleared unless it is also restarted. Excel-erator Programmer's Guide and Reference
Ping SMTP Mail Server (PINGMAIL)
Where allowed to run: All environments (*ALL) Threadsafe: No The Ping SMTP Mail Server (PINGMAIL) command establishes an SMTP connection with a remote system to insure it will process email from the local IBM i. The detailed send and receive data from the connection is recorded in the joblog and can be view using the Display Job Log (DSPJOBLOG) command. Limitation 

The data received from the remote system is not inspected. If the remote system returns an error (RC=4xx or 5xx) subsequent data in the joblog is not reliable. The command can not perform STARTTLS. Remote systems that require STARTTLS can not be tested. Note: When prompting, input fields can be expanded by typing an ampersand (&) in the first position of the field followed by a blank, and pressing enter. Parameters
Keyword Description Choices Notes RMTSYS Remote system Character value, *INTNETADR Required, Positional 1 SMTPNAME To SMTP name (email address) Character value, *NONE Optional SMTPNAME2 From SMTP name (email address) Character value, *SMTPNAME Optional AUTHUSRNAM Authentication username Character value, *NONE Optional AUTHPWD Authentication password Character value Optional PORT Port 0‐65534, 25 Optional INTNETADR Remote internet address Character value Optional Remote system (RMTSYS)
Specifies the remote system name of the host with which the Ping SMTP Mail Server operation takes place. To be successful, the name must be valid, and the remote system must be able to communicate with the local system. This is a required parameter. *INTNETADR
character-value
The INTNETADR parameter is used. Specify the remote system name to use. To SMTP name (email address) (SMTPNAME)
Specifies an email address to verify with the remote host. A short email message is sent to the address. The message is inserted directly into the mail server under test, bypassing all of IBM iʹs mail machinery. This makes it is easier to determine if a mail delivery problem is most likely caused by the mail server or by IBM iʹs configuration. *NONE
character-value
An email address is not specified. Specify the email address to use. Chapter 7 Commands
83
From SMTP name (email address) (SMTPNAME2)
Specifies the from email address included in the test message. *SMTPNAME
character-value
The To SMTP name (email address) is used as the From SMTP name (email address). Specify the email address to use. Authentication username (AUTHUSRNAM)
Specifies the user name used to authenticate with the remote system. *NONE
character-value
Authentication is not performed. Specify the user name to send to the remote system for authentication. Authentication password (AUTHPWD)
Specifies the password used to authenticate with the remote system. character-value
Specify the password to send to the remote system for authentication. Port (PORT)
Specifies the port on which the remote system is listening. 25
integer
Use the well‐known port 25 for SMTP. Specify any port in the range of 1 to 65534 on which the remote system is listening for SMTP connections. Remote internet address (INTNETADR)
Specifies the remote internet address. The internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address. If the internet address is entered from a command line, enclose the address in apostrophes. character-value
Specify the internet address of the remote system. If the internet address is entered from a command line, enclose the address in apostrophes. Examples
Example 1:
PINGMAIL
RMTSYS(system2.widget.com)
This command tests system2 in the widget.com domain to insure that it will process email. Example 2:
PINGMAIL
RMTSYS(*INTNETADR) INTNETADR('168.243.199.2')
This command tests the system at IP address 168.243.199.2 to insure that it will process email. Error messages
Parameter dependencies
MSU7009
MSU7010
When *INTNETADR is specified Remote internet address must be specified. RMTSYS(*INTNETADR) required when INTNETADR is specified. *ESCAPE messages
MSU1068
MSU1077
84
Error encountered verifying mail server. Connection to mail server at address complete, but errors occurred. Excel-erator Programmer's Guide and Reference
Retrieve Gumbo PTF (RTVGSIPTF)
Where allowed to run: All environments (*ALL) Threadsafe: No The Retrieve Gumbo PTF (RTVGSIPTF) command checks a remote system for new product PTFs, and, if available, downloads and installs them. The command assumes that IBM i has connectivity to the PTF server. Unless you are running your own internal server hosting our PTFs, this means that IBM i has access to the internet and that FTP is not blocked by a firewall. The command first checks the availability of new PTFs by retrieving a product and release specific file (Ex. q2x20LastPtf.txt) from the remote system and comparing its contents to the last PTF applied locally. If newer PTFs are available, a product and release specific PTF save file (Ex. q2x20all.svf) is downloaded, and the PTFs it contains are loaded and applied. Note: GUMBO only delivers immediate PTFs. Immediate PTFs do not require an IPL and an IPL is never performed by the command. Parameters
Keyword Description Choices LICPGM Product Character value, *THIS, 2A55DCR, 2A55DMP, 2A55RDA, 2A55RM1, Optional, 2A55SAM, 2A55SM1, 2A55SM2, 2A55XL1 Positional 1 Notes RLS Release Character value, *THIS Optional, Positional 2 CHECK Check *YES, *NO, *ONLY Optional RMTSYS Remote system Character value, *GUMBOFTP Optional Product (LICPGM)
Specifies the product for which PTFs are retrieved. All GUMBO products take the form 2A55tla where ʺtlaʺ identifies the product. Run DSPSFWRSC to determine which GUMBO products are installed. CHAR(7) *THIS
2A55DCR
2A55DMP
2A55RDA
2A55RM1
2A55SAM
2A55SM1
2A55SM2
2A55XL1
character-value
Use the product (2A55XL1) containing this copy of the Retrieve Gumbo PTF (RTVGSIPTF) command. Dicer Dumpster Report Designer Report Manager Spool‐a‐Matic SpoolMail Gumbo Mail Excel‐erator Specifies the 7‐character identifier of the product for which PTFs are retrieved. Release (RLS)
Specifies the release for which PTFs are retrieved. Run DSPSFWRSC to determine which GUMBO products are installed. CHAR(6) *THIS
character-value
Use the release of the product (V2R2M0) containing this copy of the Retrieve Gumbo PTF (RTVGSIPTF) command. Specify the release level of the product in the format VxRyMz, where Vx is the version number, Ry is the release number, and Mz is the modification level. Chapter 7 Commands
85
Check (CHECK)
Specifies if checking for newer PTFs is performed. CHAR(10) *YES
Check for newer PTFs is performed before downloading. If newer PTFs are not available, processing stops. No check for newer PTFs is performed before downloading. Only a check for newer PTF availability is performed. Nothing is downloaded, regardless of the result. *NO
*ONLY
Remote system (RMTSYS)
Specifies the name of remote system which serves PTF save files for download. CHAR(255) *GUMBOFTP
character-value
Use GUMBO's FTP server ftp.gumbo.com Specify the remote system name to use. Note: When prompting, the input field can be expanded by typing an ampersand (&) in the first position of the field followed by a blank, and pressing enter. Examples
Example 1:
RTVGSIPTF
The GUMBO FTP server is check for new PTFs available for product 2A55XL1 release V2R2M0. If available, the PTFs are downloaded and installed. Example 2:
RTVGSIPTF
PRODUCT(2A55XL1) RLS(V2R2M0) CHECK(*ONLY)
The GUMBO FTP server is check for new PTFs available for product 2A55XL1 release V2R2M0. No other processing is performed. Error messages
*ESCAPE messages
PID1007
86
Retrieve PTF failed for product . Excel-erator Programmer's Guide and Reference
Send File Excel (SNDFEXCEL)
Where allowed to run: All environments (*ALL) Threadsafe: No The Send File Excel (SNDFEXCEL) command converts one or more IBM i database files into Excel spreadsheets which are then sent as an email to recipients. Parameters
Keyword Description Choices Notes SNDF File specifications Values (up to 64 repetitions): Element list Element 1: From file Qualified object name Required, Positional 1 Qualifier 1: From file Name Qualifier 2: Library Name, *LIBL, *CURLIB Element 2: Attachment file name Character value, ʹ*FILE.*TRNEXTʹ, *APPEND, *FILE, *FILELIB, *TRNEXT, *MBR, *TEXT, *MBRCDAT, *MBRCCYY, *MBRCYY, *MBRCMM, *MBRCDD, *MBRCTIM, *MBRGDAT, *MBRGCYY, *MBRGYY, *MBRGMM, *MBRGDD, *MBRGTIM TO Element 3: From member Name, *FIRST, *LAST Element 4: Field Single values: *ALL Other values (up to 256 repetitions): Name Element 5: Sheet name Character value, *FILE, *FILELIB, *MBR, *TEXT, *MBRCDAT, *MBRCCYY, *MBRCYY, *MBRCMM, *MBRCDD, *MBRCTIM, *MBRGDAT, *MBRGCYY, *MBRGYY, *MBRGMM, *MBRGDD, *MBRGTIM Element 6: Sheet title Single values: *NONE Other values (up to 5 repetitions): Character value To (recipient) Single values: *CURRENT, *NONE Other values (up to 300 repetitions): Element list Optional, Positional 2 Element 1: Character value, *USRID, *USRPRF SUBJECT Subject Character value, *DEFAULT, *NONE COLHDG Column headings *FLDNAM, *FLDNAMBLD, *ALIAS, *ALIASBLD, *COLHDG, Optional *COLHDGBLD, *COLHD1, *COLHD1BLD, *COLTXT, *COLTXTBLD, *NONE, *TXT, *TXTBLD, *TXTCOL, *TXTCOLBLD TRANSFORM Transform *BIFF8, *CSVUTF8, *CSVUTF8M, *CSVRFC, *CSVRFCQ, *BIFF4, *XMLSS, *OOXML Optional PRTHEADER Print header Character value, *RCDTEXT, *MBRTEXT, *FILTEXT, *NONE Optional PRTFOOTER Print footer Character value, *RCDTEXT, *MBRTEXT, *FILTEXT, *NONE Optional FONT Font typeface Character value, *ARIAL, *COURIER Optional COMMENT Cell comments Single values: *NONE Other values (up to 32 repetitions): Element list Optional Element 1: Column 1‐256, A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, AA, AB, AC, AD, AE, AF, AG, AH, AI, AJ, AK, AL, AM, AN, AO, AP, AQ, AR, AS, AT, AU, AV, AW, AX, AY, AZ, BA, BB, BC, BD, BE, BF, BG, BH, BI, BJ, BK, BL, BM, BN, BO, BP, BQ, BR, BS, BT, BU, BV, BW, BX, BY, BZ, CA, CB, CC, CD, CE, CF, CG, CH, CI, CJ, CK, CL, CM, CN, CO, CP, CQ, CR, CS, CT, CU, CV, CW, CX, CY, CZ, DA, DB, DC, DD, DE, DF, DG, DH, DI, DJ, DK, DL, DM, DN, DO, DP, DQ, DR, DS, DT, DU, DV, DW, DX, DY, DZ, EA, EB, EC, ED, EE, EF, EG, EH, EI, EJ, EK, EL, EM, EN, EO, EP, EQ, ER, ES, ET, EU, EV, EW, EX, EY, EZ, FA, FB, FC, FD, FE, FF, FG, FH, FI, FJ, FK, FL, FM, FN, FO, FP, FQ, FR, FS, FT, FU, FV, FW, FX, FY, FZ, GA, GB, GC, GD, GE, GF, GG, GH, GI, GJ, GK, GL, GM, GN, GO, GP, GQ, GR, GS, GT, GU, GV, GW, GX, GY, GZ, HA, HB, HC, HD, HE, HF, HG, HH, HI, HJ, HK, HL, HM, HN, HO, HP, HQ, HR, HS, HT, HU, HV, HW, HX, HY, HZ, IA, IB, IC, ID, IE, IF, IG, IH, II, IJ, IK, IL, IM, IN, IO, IP, IQ, IR, IS, IT, IU, IV Chapter 7 Commands
Optional, Positional 3 87
Element 2: Row 1‐65536, 1 Element 3: Text Character value MSG Message Character value, *DEFAULT, *NONE Optional CC Cc (carbon copy) Single values: *NONE Other values (up to 300 repetitions): Element list Optional Element 1: Character value, *CURRENT, *USRID, *USRPRF BCC Bcc (blind carbon copy) Single values: *NONE Other values (up to 300 repetitions): Element list Optional Element 1: Character value, *CURRENT, *USRID, *USRPRF FROM From (originator) Character value, *CURRENT Optional CFMDEL Confirmation of delivery *NO, *YES, *OBS, Y, N, O Optional REPLYTO Reply to Single values: *NONE Other values (up to 300 repetitions): Element list Optional Element 1: Character value, *CURRENT, *USRID, *USRPRF INCOBJ Include object Single values: *NONE Other values (up to 64 repetitions): Element list Element 1: Name Path name Element 2: Send as *NOTE, *ATTACH, *TEXTPLAIN, *TEXTHTML, *ATTACHPDF, *ATTACHPS Optional Element 3: Multipart/alternative 1‐9, *NONE group CHRENC Character encoding of mail *UTF8, *ISO88591, *ISO88592, *ISO88595, *ISO88596, *ISO88597, Optional *ISO88598, *ISO88599, *BIG5, 1208, 819, 912, 915, 1089, 813, 916, 920, 950 FILESHARE File sharing Element list Element 1: Password to open Character value Element 2: Password to modify Character value Element 3: Read‐only recommended *NO, *YES, N, Y Column heading format Single values: *DEFAULT Other values: Element list COLHDGFMT Optional Optional Element 1: Alignment‐Horizontal *GENERAL, *TYPE, *LEFT, *CENTER, *RIGHT, *FILL, *JUSTIFY, *CENTERSEL, 0, 1, 2, 3, 4, 5, 6, 8 Element 2: Border‐Top line style *NONE, *THIN, *MEDIUM, *DASHED, *DOTTED, *THICK, *DOUBLE, *HAIR, 0, 1, 2, 3, 4, 5, 6, 7 Element 3: Border‐Left line style *NONE, *THIN, *MEDIUM, *DASHED, *DOTTED, *THICK, *DOUBLE, *HAIR, 0, 1, 2, 3, 4, 5, 6, 7 Element 4: Border‐Bottom line style *NONE, *THIN, *MEDIUM, *DASHED, *DOTTED, *THICK, *DOUBLE, *HAIR, 0, 1, 2, 3, 4, 5, 6, 7 Element 5: Border‐Right line style *NONE, *THIN, *MEDIUM, *DASHED, *DOTTED, *THICK, *DOUBLE, *HAIR, 0, 1, 2, 3, 4, 5, 6, 7 Element 6: Border‐Top line color *SYSTEM, *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 32767, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Element 7: Border‐Left line color *SYSTEM, *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 32767, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Element 8: Border‐Bottom line color 88
*SYSTEM, *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, Excel-erator Programmer's Guide and Reference
*COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 32767, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Element 9: Border‐Right line color *SYSTEM, *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 32767, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Element 10: Patterns‐Type *NONE, *SOLID, *GRAY75, *GRAY50, *GRAY25, *GRAY12, *GRAY6, *STRIPEH50, *STRIPEH25, *STRIPEV50, *STRIPEV25, *STRIPED50, *STRIPED25, *STRIPEDR50, *STRIPEDR25, *HATCHD75, *HATCHD50, *HATCHD38, *HATCHH38, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18 Element 11: Patterns‐Foreground *AUTOMATIC, *BLACK, *WHITE, *RED, *BRIGHTGREEN, color *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 24, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 Element 12: Patterns‐Background *AUTOMATIC, *BLACK, *WHITE, *RED, *BRIGHTGREEN, color *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50, *COLOR1, *COLOR2, *COLOR3, *COLOR4, *COLOR5, *COLOR6, *COLOR7, *COLOR8, *COLOR9, *COLOR10, *COLOR11, *COLOR12, *COLOR13, *COLOR14, *COLOR15, *COLOR16, 25, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 PALETTE SGNKEY Element 13: Protection‐Locked *YES, *NO, 0, 1 Color palette Values (up to 16 repetitions): Element list Element 1: Color to replace *BLACK, *WHITE, *RED, *BRIGHTGREEN, *BLUE, *YELLOW, *PINK, *TURQUOISE, *DARKRED, *GREEN, *DARKBLUE, *DARKYELLOW, *VIOLET, *TEAL, *GRAY25, *GRAY50 Element 2: Red component 0‐255 Element 3: Green component 0‐255 Element 4: Blue component 0‐255 Signing key Single values: *DEFAULT, *NONE Other values: Element list Optional Optional Element 1: Application ID Character value CSVSEPCHR CSV separator character Character value, *COMMA, *PERIOD, *PIPE, *SEMICOLON, *SLASH, *TAB Optional PAGESETUP Page setup Single values: *NONE Other values: Element list Optional Element 1: Paper size *LETTER, *LEGAL, *STATEMENT, *EXECUTIVE, *LEDGER, *A3, *A4, *A5, *B4, *B5, 1, 4, 5, 6, 7, 8, 9, 11, 12, 13 Element 2: Orientation *PORTRAIT, *LANDSCAPE, 0, 1 Element 3: Scale to % normal size 10‐400, *AUTO Element 4: Scale to page(s) wide 1‐32767, *AUTO Element 5: Scale to page(s) tall 1‐32767, *AUTO Element 6: Print gridlines *NO, *YES, 0, 1 Element 7: Print black and white *NO, *YES, 0, 1 Element 8: Print draft quality *NO, *YES, 0, 1 Element 9: Print row and column *NO, *YES, 0, 1 headings FREEZEPANE Element 10: Print comments *NONE, *DSP, *END, 0, 2, 3 Element 11: Print order *DOWN, *OVER, 0, 1 Freeze pane Single values: *NO Other values: Element list Chapter 7 Commands
Optional 89
Element 1: Rows to freeze *CALC, *NONE, ‐2 Element 2: Columns to freeze Integer, *NONE PRIORITY Priority *NONE, *HIGHEST, *HIGH, *NORMAL, *LOW, *LOWEST, *HIGHO, *NORMALO, *LOWO Optional SHEETOPT Sheet option Element list Optional Element 1: Right to left *CONTEXT, *NO, *YES, 0, 1, 2 TRGCCSID Target coded character set id 1‐65533, 1252 Optional SRCCCSID Source coded character set id 1‐65533, *KBDTYPE, *SYSVAL, *JOBDFT Optional TOUSRID To (distribution list) Single values: *NONE Other values: Element list Optional Element 1: User ID Character value Element 2: Address Character value File specifications (SNDF)
Specifies one or more database files that are sent, the attachment file name for each file as it appears in the email, the member name to be sent for each file, and the list of fields to be included for each file. CHAR(10), CHAR(10), CHAR(32), CHAR(10), CHAR(10), CHAR(80) This is a required parameter. Element 1: From file
The name and library of a database file. Qualifier 1: From file name
Qualifier 2: Library
*LIBL
*CURLIB
name
Specify the name of the file. All libraries in the threadʹs library list are searched. Use the current library for the job. If no library is specified as the current library for the job, QGPL is used. Specify the name of the library. Element 2: Attachment file name
*FILE.*TRNEXT
*APPEND
The name is made up of the database file name with an extension based on the transform specified. The database file does not result in a separate Excel spreadsheet. Instead, a worksheet is generated and appended (added to) the preceding Excel spreadsheet. Note: When this value is used, it must be the only value entered in the command element. name
Specify the name of the attached file. Excel‐erator provides several special values that can used to construct dynamic object (stream file) names. When the special values are found, the associated data is blank trimmed and substituted into the path specified when it is processed. If the data associated with a special value is blank, ʹBLANKʹ is substituted. If the data associated with a special value contains characters not allowed in an object name, question marks (ʹ?ʹ) for example, the name will be invalid and the command will fail. The special values must be delimited by an underscore (ʹ_ʹ) a period (ʹ.ʹ) a slash (ʹ/ʹ or ʹ\ʹ) a dash (ʹ‐ʹ) or another special value (which starts with ʹ*ʹ). The transform related special values are: *TRNEXT
Transform dependent file extension CHAR(3) or CHAR(4).  XLS for *BIFF8 or *BIFF4.  csv for *CSVUTF8, *CSVUTF8M, *CSVRFC, or *CSVRFCQ  xml for *XMLSS.  xlsx for *OOXML. The member related special values are: *FILE
90
File name CHAR(10). Excel-erator Programmer's Guide and Reference
*FILELIB
*MBR
*TEXT
*MBRCDAT
*MBRCCYY
*MBRCYY
*MBRCMM
*MBRCDD
*MBRCTIM
*MBRGDAT
*MBRGCYY
*MBRGYY
*MBRGMM
*MBRGDD
*MBRGTIM
Library containing the file CHAR(10). Member name CHAR(10). Member Text ʹdescriptionʹ CHAR(50). Date the member was created CHAR(7) CYYMMDD. CYY portion of *MBRCDAT CHAR(3). YY portion of *MBRCDAT CHAR(2). MM portion of *MBRCDAT CHAR(2). DD portion of *MBRCDAT CHAR(2). Time the member was created CHAR(6) HHMMSS. Date the member was changed CHAR(7) CYYMMDD. CYY portion of *MBRGDAT CHAR(3). YY portion of *MBRGDAT CHAR(2). MM portion of *MBRGDAT CHAR(2). DD portion of *MBRGDAT CHAR(2). Time the member was changed CHAR(6) HHMMSS. Element 3: From member
*FIRST
*LAST
name
The first member in the database from‐file is processed. The last member in the database from‐file is processed. Specify the name of the database from‐file member to process. Element 4: Field
Single values
Other values
*ALL
name
All fields in the database file are included in the spreadsheet in the order they appear in the file. Specify the list of field names to be included in the spreadsheet. The fields appear in the spreadsheet in the order specified, duplicates are allowed. Element 5: Sheet name
Specifies the name of the worksheet. CHAR(32) *MBR
character-value
The member name is the sheet name. Specify up to 32 characters enclosed in apostrophes. Excel‐erator provides several special values that can used to construct dynamic sheet names. When the special values are found, the associated data is blank trimmed and substituted into the name specified when it is processed. If the data associated with a special value is blank, ʹBLANKʹ is substituted. The special values must be delimited by an underscore (_) a period (ʹ.ʹ) or another special value (which starts with ʹ*ʹ). The result is trimmed if the length is exceeded. *FILE
*FILELIB
*MBR
*TEXT
*MBRCDAT
*MBRCCYY
*MBRCYY
*MBRCMM
*MBRCDD
*MBRCTIM
*MBRGDAT
*MBRGCYY
*MBRGYY
*MBRGMM
*MBRGDD
*MBRGTIM
File name CHAR(10). Library containing the file CHAR(10). Member name CHAR(10). Member Text ʹdescriptionʹ CHAR(50). Date the member was created CHAR(7) CYYMMDD. CYY portion of *MBRCDAT CHAR(3). YY portion of *MBRCDAT CHAR(2). MM portion of *MBRCDAT CHAR(2). DD portion of *MBRCDAT CHAR(2). Time the member was created CHAR(6) HHMMSS. Date the member was changed CHAR(7) CYYMMDD. CYY portion of *MBRGDAT CHAR(3). YY portion of *MBRGDAT CHAR(2). MM portion of *MBRGDAT CHAR(2). DD portion of *MBRGDAT CHAR(2). Time the member was changed CHAR(6) HHMMSS. Chapter 7 Commands
91
Element 6: Sheet title
Specifies the title of the worksheet. CHAR(80) Note: When prompting, the input field can be expanded by typing an ampersand (&) in the first position of the field followed by a blank, and pressing enter. Single values
Other values
Title lines are not included in the sheet. *NONE
character-value Specify up to 80 characters enclosed in apostrophes. To (recipient) (TO)
Specifies the email address(es) to which the generated email is sent. Up to 300 addresses can be specified. CHAR(128) Single values
*CURRENT
*NONE
The email address stored in the directory entry associated with the user running the command is used. An email address is not specified. Other values (up to 300 repetitions)
character-value
Specify the email address of the recipient. Subject (SUBJECT)
Specifies the subject for the generated email. CHAR(60) *DEFAULT
*NONE
character-value
The subject of the email is generated from the file specification. No subject is included in the email. Specify the subject of the email. Column headings (COLHDG)
Specifies the column headings generated. CHAR(10) *FLDNAM
*FLDNAMBLD
*ALIAS
*ALIASBLD
*COLHDG
*COLHDGBLD
*COLHD1
*COLHD1BLD
*COLTXT
*COLTXTBLD
*NONE
*TXT
*TXTBLD
*TXTCOL
*TXTCOLBLD
92
The fileʹs field names are used as column headings. The fileʹs field names are used as column headings. The column headings are bold. The fileʹs field aliases are used as column headings. The fileʹs field aliases are used as column headings. The column headings are bold. The fileʹs field column headings are used as column headings. The fileʹs field column headings are used as column headings. The column headings are bold. The fileʹs field column headings are used as column headings. A heading with multiple lines is text wrapped into a single cell. The fileʹs field column headings are used as column headings. A heading with multiple lines is text wrapped into a single cell. The column headings are bold. The fileʹs field column headings are used as column headings. A heading with multiple lines is text wrapped into a single cell. If the column headings are blank, the field text is used. The fileʹs field column headings are used as column headings. A heading with multiple lines is text wrapped into a single cell. If the column headings are blank, the field text is used. The column headings are bold. No column headings are included. The fileʹs field texts are used as column headings. The fileʹs field texts are used as column headings. The column headings are bold. The fileʹs field texts are used as column headings. If the field text is blank the field column heading are used. A heading with multiple lines is text wrapped into a single cell. The fileʹs field texts are used as column headings. If the field text is blank the field column heading are used. A heading with multiple lines is text wrapped into a single cell. The column headings are bold. Excel-erator Programmer's Guide and Reference
Transform (TRANSFORM)
Specifies the target format to which the data is transformed. CHAR(10). *BIFF8
*CSVUTF8
*CSVUTF8M
*CSVRFC
*CSVRFCQ
*XMLSS
*OOXML
*BIFF4
Microsoftʹs Binary Interchange File Format Version 8, the format used by Excel version 8.0 (Excel 97/98), Excel 9.0 (Excel 2000/2001), Excel 10.0 (Excel XP/v.X) and Excel 11.0 (Excel 2003/2004). Comma Separated Values (CSV) format. Data is converted to UTF‐8. Trailing blanks are trimmed. Comma Separated Values (CSV) format. Data is converted to UTF‐8 and Byte Order Mark xEFBBBF is inserted at the start of the file. Trailing blanks are trimmed. Comma Separated Values (CSV) format. Data is converted to US‐ASCII in strict compliance with RFC4180 Common Format and MIME Type for Comma‐Separated Values (CSV) Files. Quoting is avoided unless need data containing quotes. Trailing blanks are trimmed. Comma Separated Values (CSV) format. Data is converted to US‐ASCII in strict compliance with RFC4180 DOUBLE QUOTED Common Format and MIME Type for Comma‐Separated Values (CSV) Files. Character data is always quoted. Trailing blanks are trimmed. Microsoftʹs Excel specific ʺXML Spreadsheet formatʺ introduced with Excel 2002 and Excel 2003. Office Open XML developed by Microsoft. Excel‐erator implements the ISO/IEC 29500:2008 Strict specification, suitable for use with Excel 2010 and suitable for use with Excel 2007 if dates are not present in the spreadsheet. See http://en.wikipedia.org/wiki/Office_Open_XML for additional information. Microsoftʹs Binary Interchange File Format Version 4, the format used by Excel version 4.0 (Excel 4.0). Note: Use *BIFF8 instead of *BIFF4. *BIFF4 is included for compatibility with existing software and is no longer being enhanced. Print header (PRTHEADER)
Specifies the print header placed in the spreadsheet. CHAR(50) *NONE
*RCDTEXT
*MBRTEXT
*FILTEXT
character-value
No print header is included in the file. The record text is used as the print header. The member text is used as the print header. The file text is used as the print header. Enter the value to use as the print header. The header text can include the standard Excel codes: &A
Inserts the worksheet name &B
Toggles bold &C
Start of centered section &D
Inserts the current date &E
Toggles double‐underline &F
Inserts the workbook name &I
Toggles italic &L
Start of left section &N
Inserts the total page count &R
Start of right section &S
Toggles strikethrough &T
Inserts the current time &[Tab]
Inserts the worksheet name &U
Toggles underline &X
Toggles superscript &Y
Toggles subscript &P
Inserts the current page number &P+n
Inserts the page number incremented by n &P-n
Inserts the page number decremented by n &[Path]
Inserts the workbook path &&
Escapes the ampersand character &"fontname" Selects the named font Selects the specified 2‐digit font point size &nn
Chapter 7 Commands
93
Print footer (PRTFOOTER)
Specifies the print footer placed in the spreadsheet. CHAR(50) *NONE
*RCDTEXT
*MBRTEXT
*FILTEXT
character-value
No print footer is included in the file. The record text is used as the print footer. The member text is used as the print footer. The file text is used as the print footer. Enter the value to use as the print footer. The footer text can include the standard Excel codes: &A
Inserts the worksheet name &B
Toggles bold &C
Start of centered section &D
Inserts the current date &E
Toggles double‐underline &F
Inserts the workbook name &I
Toggles italic &L
Start of left section &N
Inserts the total page count &R
Start of right section &S
Toggles strikethrough &T
Inserts the current time &[Tab]
Inserts the worksheet name &U
Toggles underline &X
Toggles superscript &Y
Toggles subscript &P
Inserts the current page number &P+n
Inserts the page number incremented by n &P-n
Inserts the page number decremented by n &[Path]
Inserts the workbook path &&
Escapes the ampersand character &"fontname" Selects the named font Selects the specified 2‐digit font point size &nn
Font typeface (FONT)
Specifies the font name placed into the file. The font specified must be available on the PC that is running Excel. CHAR(32). *ARIAL
*COURIER
character-value
Font Arial is used. Font Courier New, a fixed pitch font, is used. The name of the font to use. Cell comments (COMMENT)
Specifies cell comments, consisting of a cellʹs coordinate column/row and the comment text, which are added to the generated spreadsheet. A comment can be added to a cell even if it does not contain data. INT(4) (where A=1, B=2, etc.), INT(4) CHAR(2048) Single values
*NONE
No comments are added to the spreadsheet. Element 1: Column
1-256
The column of the cell that receives the comment. You can use either a letter or number designation. Element 2: Row
1-65536
94
The row of the cell that receives the comment. Excel-erator Programmer's Guide and Reference
Element 3: Text
character-value
Enter the text that is to appear in the comment. Message (MSG)
Specifies a message to include in the generated email. CHAR(2048) *DEFAULT
*NONE
character-value
The message in the email is generated from the file specification. This parameter does not place a message in the email. Specify the message placed in the email. Cc (carbon copy) (CC)
Specifies the email address(es) to which a copy is sent. Up to 300 addresses can be specified. CHAR(128) Single values
*NONE
An email address is not specified. Other values (up to 300 repetitions)
*CURRENT
*USRID
character-value
The email address stored in the directory entry associated with the user running the command is used. Specify the directory entry or distribution list that supplies the email address(es). The correct form is: *USRID:NAME:ADDRESS where NAME is either a directory entryʹs ʺUser IDʺ or a distribution listʹs ʺList IDʺ and where ADDRESS is either a directory entryʹs ʺAddressʺ or a distribution listʹs ʺList ID qualifierʺ. The email address found on the directory entry, or the email address found on each directory entry found on the distribution list, is/are used. Specify the email address to receive a copy. Bcc (blind carbon copy) (BCC)
Specifies the email address(es) to which a blind copy is sent. Up to 300 addresses can be specified. CHAR(128) Single values
*NONE
An email address is not specified. Other values (up to 300 repetitions)
*CURRENT
*USRID
character-value
The email address stored in the directory entry associated with the user running the command is used. Specify the directory entry or distribution list that supplies the email address(es). The correct form is: *USRID:NAME:ADDRESS where NAME is either a directory entryʹs ʺUser IDʺ or a distribution listʹs ʺList IDʺ and where ADDRESS is either a directory entryʹs ʺAddressʺ or a distribution listʹs ʺList ID qualifierʺ. The email address found on the directory entry, or the email address found on each directory entry found on the distribution list, is/are used. Specify the email address to receive a blind copy. From (originator) (FROM)
Specifies the email address that appears as the From on the generated the email. You can use this to control the address used when the recipient replies to the email. Note: One or more of the special values for this parameter access the system distribution directory to determine an email address based on the implied user profile. If the user profile does not have a directory entry (I.e. the user has not been enrolled), the user name is used to construct an email address. If the user has been enrolled but an email address has not been specified on the directory entry, the user id and address are used to construct an email address. In either case, the constructed address, in all likelihood, is not a valid email address. The email will deliver but recipient replies will be lost (bounce). *CURRENT
character-value
The email address stored in the directory entry associated with the user running the command is used. Specify the email address of the originator. Chapter 7 Commands
95
Confirmation of delivery (CFMDEL)
Specifies whether a request for a read receipt is sent with the message. Message recipients can choose whether or not to send receipts. If the message recipient agrees to send a read receipt, the receipt will be sent when the message is opened. *NO
*YES
*OBS
Confirmation of delivery is not requested. Confirmation of delivery is requested. Confirmation of delivery is requested as with *YES but the obsolete non‐standard ʺReturn‐Receipt‐Toʺ header field is also included in the message. Some mail user/transport agents understand the obsolete field but do not understand the standard ʺDisposition‐Notification‐Toʺ supplied by *YES. Reply to (REPLYTO)
Specifies the email address(es) to which replies should be sent when replies should go to an address other than the From (originator) (FROM) parameter or to multiple addresses. Up to 300 addresses can be specified. CHAR(128) Single values
*NONE
Replies are directed to the address the email is from. Other values (up to 300 repetitions)
*CURRENT
*USRID
character-value
The email address stored in the directory entry associated with the user running the command is used. Specify the directory entry or distribution list that supplies the email address(es). The correct form is: *USRID:NAME:ADDRESS where NAME is either a directory entryʹs ʺUser IDʺ or a distribution listʹs ʺList IDʺ and where ADDRESS is either a directory entryʹs ʺAddressʺ or a distribution listʹs ʺList ID qualifierʺ. The email address found on the directory entry, or the email address found on each directory entry found on the distribution list, is/are used. Specify the email address to which replies should be directed. Include object (INCOBJ)
Specifies the path name of an additional object (stream file) to include in the generated email message. For example, a stream file containing standard terms and conditions can be included as an additional attachment. A maximum of 64 path names can be specified. For more information on specifying path names, see Programming > Control language > CL concepts > IBM i objects > Object naming rules topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. CHAR(5000) Single values
*NONE
No objects are sent. Element 1: Name
path-name
Specify an object path name. Element 2: Send as
*ATTACH
*TEXTPLAIN
Send the object as an attached file using MIME and specifying ʺapplication/octet‐streamʺ. Copy the object into the body of the mail message specifying content type text/plain. The CCSID of the file must match the value specified for CHRENC(). Note: Some servers disregard this request and form an attachment from the message in all cases. Some servers disregard this request for the second and subsequent body parts. If this is the case, try MSG(*NONE). *TEXTHTML
Copy the object into the body of the mail message specifying content type text/html. The CCSID of the file must match the value specified for CHRENC(). Note: Some servers disregard this request and form an attachment from the message in all cases. Some servers disregard this request for the second and subsequent body parts. If this is the case, try MSG(*NONE). 96
Excel-erator Programmer's Guide and Reference
*ATTACHPDF
*ATTACHPS
*NOTE
Send the object as an attached file using MIME and specifying ʺapplication/pdfʺ. Use this value if the attached file contains Adobeʹs Portable Document Format (pdf) data. Send the object as an attached file using MIME and specifying ʺapplication/postscriptʺ. Use this value if the attached file contains postscript data. Same as *TEXTPLAIN which is preferred. Element 3: Multipart/alternative group
*NONE
1-9
The object is not a member of a ʺmultipart/alternativeʺ group. Specify a group number for forming ʺmultipart/alternativeʺ groups. All objects with the same group number are members of a ʺmultipart/alternativeʺ in the generated email. Character encoding of mail (CHRENC)
Specifies the character set used to create the email and MIME headers (the transfer encoding). *UTF8
*ISO88591
*ISO88592
*ISO88595
*ISO88596
*ISO88597
*ISO88598
*ISO88599
*BIG5
Unicode 8 bit transfer encoding (1208). ISO‐8859‐1 Latin 1 Western European ʺ8‐bit ASCIIʺ (819). ISO‐8859‐2 ROECE Latin 2 Eastern European (912). ISO‐8859‐5 Cyrillic (915). ISO‐8859‐6 Arabic (1089). ISO‐8859‐7 Greek (813). ISO‐8859‐8 Hebrew (916). ISO‐8859‐9 Latin 9 other Latin‐using languages (920). Traditional Chinese, Taiwan Industry Standard PC Data Mixed for Big5 (950). File sharing (FILESHARE)
Specifies how the generated spreadsheet is secured. Each element corresponds to an Excel setting accessible from the ʺSave Asʺ dialog. The limitations, and resulting encryption strength vary significantly between *BIFF8 and *BIFF4 and are documented separately. For *BIFF8
Element 1: Password to open
character-value
Specifies the case sensitive password required to open and decrypt the file. If a password is not specified, the file is not encrypted and can be opened by anyone. CHAR(15) Any character, including DBCS, can be included in the password. The spreadsheet is encrypted using the RC4 algorithm. Element 2: Password to modify
character-value
Specifies the case sensitive password required to update the file. If a password is specified and someone changes the file without the password, that person can save the file only by giving it a different name. If a password is not specified, the file can be updated by anyone. This password does not cause the file to be encrypted. CHAR(15) Excel‐erator restricts this password to a‐z, A‐Z, 0‐9, the space character and symbols !ʺ#$%&ʹ()*+,‐
./:;<=>?@[\]^_`{|}~. That is the ascii code points from x20‐x7E which map directly to UTF8 and the base plane of unicode. With this restriction, the password can be typed by virtually any recipient, without knowing the details of their keyboard or code page of their machine. Note: The security of Password to modify is notoriously weak. Element 3: Read-only recommended
*NO
*YES
No recommendation given. CHAR(1) value ʹNʹ. Specifies that users get a read‐only (read‐only: A setting that allows a file to be read or copied but not changed or saved.) recommendation when they open the file. This does not prevent users from opening the file as read‐write so that they can edit and save changes. CHAR(1) value ʹYʹ. Chapter 7 Commands
97
For *BIFF4
*BIFF4 security is notoriously insecure and may not be suitable for all environments. Password crackers are freely available. While not a requirement, for best results use a password that contains only characters a‐z, A‐Z, 0‐9, the space character and symbols !ʺ#$%&ʹ()*+,‐./:;<=>?@[\]^_`{|}~. This insures compatibility with Excel Macintosh edition, for example. Element 1: Password to open
character-value
Specifies the case sensitive password required to open and decrypt the file. If a password is not specified, the file is not encrypted and can be opened by anyone. CHAR(15) Element 2: Password to modify
character-value
Specifies the case sensitive password required to update the file. If a password is specified and someone changes the file without the password, that person can save the file only by giving it a different name. If a password is not specified, the file can be updated by anyone. This password does not cause the file to be encrypted. CHAR(15) Element 3: Read-only recommended
*NO
*YES
No recommendation given. CHAR(1) value ʹNʹ. Specifies that users get a read‐only (read‐only: A setting that allows a file to be read or copied but not changed or saved.) recommendation when they open the file. This does not prevent users from opening the file as read‐write so that they can edit and save changes. CHAR(1) value ʹYʹ. Column heading format (COLHDGFMT)
Specifies formatting applied to the cells containing column headings. Each element corresponds to an Excel setting accessible by selecting Format > Cells. The values that each element accepts have their usual Excel meanings with one exception: ʺAlignment‐Horizontalʺ accepts a *TYPE special value, which is not available in Excel. When *TYPE is specified, the column headings of character fields are given *LEFT horizontal alignment while the column headings of numeric fields are given *RIGHT horizontal alignment. See Excelʹs help for additional information. Each element is INT(2). Single values
*DEFAULT
Default values are used. Element 1: Alignment-Horizontal
Specifies alignment of text within cells. *GENERAL
*TYPE
*LEFT
*CENTER
*RIGHT
*FILL
*JUSTIFY
*CENTERSEL
Cells are given Excelʹs ʺGeneralʺ alignment. Alignment is determined by the fieldʹs data type: right for numeric fields, left for character fields. Cells are given Excelʹs ʺLeftʺ alignment. Cells are given Excelʹs ʺCenterʺ alignment. Cells are given Excelʹs ʺRightʺ alignment. Cells are given Excelʹs ʺFillʺ alignment. Cells are given Excelʹs ʺJustifyʺ alignment. Cells are given Excelʹs ʺCenter Across Selectionʺ alignment. Element 2-5: Border-Line styles.
Specify the Top/Left/Bottom/Right border line styles. *NONE
*THIN
*MEDIUM
*DASHED
*DOTTED
98
Line is removed. Line is thin. Line is medium. Line is dashed. Line is dotted. Excel-erator Programmer's Guide and Reference
*THICK
*DOUBLE
*HAIR
Line is thick. Line is doubled. Line is hair. Element 6-9: Border-Line colors.
Specify the Top/Left/Bottom/Right border line colors. *SYSTEM
*BLACK
*WHITE
*RED
*BRIGHTGREEN
*BLUE
*YELLOW
*PINK
*TURQUOISE
*DARKRED
*GREEN
*DARKBLUE
*DARKYELLOW
*VIOLET
*TEAL
*GRAY25
*GRAY50
System default color. Same as *COLOR1. Red=0, Green=0, Blue=0 Same as *COLOR2. Red=255, Green=255, Blue=255 Same as *COLOR3. Red=255, Green=0, Blue=0 Same as *COLOR4. Red=0, Green=255, Blue=0 Same as *COLOR5. Red=0, Green=0, Blue=255 Same as *COLOR6. Red=255, Green=255, Blue=0 Same as *COLOR7. Red=255, Green=0, Blue=255 Same as *COLOR8. Red=0, Green=255, Blue=255 Same as *COLOR9. Red=128, Green=0, Blue=0 Same as *COLOR10. Red=0, Green=128, Blue=0 Same as *COLOR11. Red=0, Green=0, Blue=128 Same as *COLOR12. Red=128, Green=128, Blue=0 Same as *COLOR13. Red=128, Green=0, Blue=128 Same as *COLOR14. Red=0, Green=128, Blue=128 Same as *COLOR15. Red=192, Green=192, Blue=192 Same as *COLOR16. Red=128, Green=128, Blue=128 Element 10: Patterns-Type
Specifies the pattern to apply. *NONE
*SOLID
*GRAY75
*GRAY50
*GRAY25
*GRAY12
*GRAY6
*STRIPEH50
*STRIPEH25
*STRIPEV50
*STRIPEV25
*STRIPED50
*STRIPED25
*STRIPEDR50
*STRIPEDR25
*HATCHD75
*HATCHD50
*HATCHD38
*HATCHH38
No pattern is used. Excelʹs ʺSolidʺ pattern. Excelʹs ʺ75% Grayʺ pattern. Excelʹs ʺ50% Grayʺ pattern. Excelʹs ʺ25% Grayʺ pattern. Excelʹs ʺ12.5% Grayʺ pattern. Excelʹs ʺ6.25% Grayʺ pattern. Excelʹs ʺHorizontal Stripeʺ pattern. Excelʹs ʺThin Horizontal Stripeʺ pattern. Excelʹs ʺVertical Stripeʺ pattern. Excelʹs ʺThin Vertical Stripeʺ pattern. Excelʹs ʺDiagonal Stripeʺ pattern. Excelʹs ʺThin Diagonal Stripeʺ pattern. Excelʹs ʺReverse Diagonal Stripeʺ pattern. Excelʹs ʺThin Reverse Diagonal Stripeʺ pattern. Excelʹs ʺThick Diagonal Crosshatchʺ pattern. Excelʹs ʺDiagonal Crosshatchʺ pattern. Excelʹs ʺThin Diagonal Crosshatchʺ pattern. Excelʹs ʺThin Horizontal Crosshatchʺ pattern. Element 11-12: Patterns-Colors
Specify the foreground and background pattern colors. *AUTOMATIC
*BLACK
*WHITE
*RED
*BRIGHTGREEN
*BLUE
System default color. Same as *COLOR1. Red=0, Green=0, Blue=0 Same as *COLOR2. Red=255, Green=255, Blue=255 Same as *COLOR3. Red=255, Green=0, Blue=0 Same as *COLOR4. Red=0, Green=255, Blue=0 Same as *COLOR5. Red=0, Green=0, Blue=255 Chapter 7 Commands
99
*YELLOW
*PINK
*TURQUOISE
*DARKRED
*GREEN
*DARKBLUE
*DARKYELLOW
*VIOLET
*TEAL
*GRAY25
*GRAY50
Same as *COLOR6. Red=255, Green=255, Blue=0 Same as *COLOR7. Red=255, Green=0, Blue=255 Same as *COLOR8. Red=0, Green=255, Blue=255 Same as *COLOR9. Red=128, Green=0, Blue=0 Same as *COLOR10. Red=0, Green=128, Blue=0 Same as *COLOR11. Red=0, Green=0, Blue=128 Same as *COLOR12. Red=128, Green=128, Blue=0 Same as *COLOR13. Red=128, Green=0, Blue=128 Same as *COLOR14. Red=0, Green=128, Blue=128 Same as *COLOR15. Red=192, Green=192, Blue=192 Same as *COLOR16. Red=128, Green=128, Blue=128 Element 13: Protection-Locked
Specifies if the cells are locked. Locking cells or hiding formulas has no effect unless the worksheet is protected. *YES
*NO
Cells are locked. Cells are not locked. Color palette (PALETTE)
Specifies replacements for the default colors included in the spreadsheetʹs palette. The color palette is made up of the specification for sixteen colors, numbered 1 through 16, and assigned names such as *BLACK, *RED, etc. Each color in turn is made up of the specification for the amount of red, green, and blue (RGB) components that make up the color. The amount is a number between 0 and 255. The larger the amount, the more of the component present. You can determine the RGB values for a specific color using Excelʹs Tools > Options > Color > Custom tab. INT(2), INT(2), INT(2) repeated 16 times. You specify a replacement for a default color by specifying its name and the new RGB values to use. If a color is modified then all references to the colorʹs name, used in other parameters, are also modified. For example, if color *BLACK is changed to (255 106 0), color *BLACK becomes orange and all parameters that specify *BLACK will produce this orange. Element 1: Color to replace
color-name
Specify the name to modify, example *BLACK. Element 2: Red component
integer
Specify the red RGB component. Element 3: Green component
integer
Specify the green RGB component. Element 4: Blue component
integer
Specify the blue RGB component. Signing key (SGNKEY)
Specifies the digital certificate used to sign the email. The signature included with the email allows the recipient to validate the identity of the sender and provides additional assurance that the email has not been tampered with after it is signed. A certificate is referenced by specifying the name (Application ID) of an object signing application created using IBM iʹs Digital Certificate Manager. *DEFAULT
*NONE
100
The certificate previously entered using the CHGXL1DFT command is used. No signing operation is performed. Excel-erator Programmer's Guide and Reference
application-id
Specify the application identifier to use in the signing operation. CSV separator character (CSVSEPCHR)
Specifies the character used to separate fields in the generated file. CHAR(1). Note: This parameter is ignored for transforms except those that generate Comma Separated Value (CSV). *COMMA
*PERIOD
*PIPE
*SEMICOLON
*SLASH
*TAB
character-value
Values are separated by a ʹ,ʹ. Values are separated by a ʹ.ʹ. Values are separated by a ʹ|ʹ. Values are separated by a ʹ;ʹ. Values are separated by a ʹ/ʹ. Values are separated by a horizontal tab. Specify the character. Page setup (PAGESETUP)
Specifies page set up information included in the spreadsheet. Single values
*NONE
No page set up information is included in the spreadsheet. Element 1: Paper size
Specifies the paper size to print. INT(2) *LETTER
*LEGAL
*STATEMENT
*EXECUTIVE
*LEDGER
*A3
*A4
*A5
*B4
*B5
Use letter paper with a page size of 8.5ʺ x 11ʺ. Use legal paper with a page size of 8.5ʺ x 14ʺ. Use statement paper with a page size of 5.5ʺ x 8.5ʺ. Use executive paper with a page size of 7.25ʺ x 10.5ʺ. Use ledger paper with a page size of 11ʺ x 17ʺ. Use A3 paper with a page size of 297 mm x 420 mm. Use A4 paper with a page size of 210 mm x 297 mm. Use A5 paper with a page size of 148 mm x 210 mm. Use B4 paper with a page size of 250 mm x 353 mm. Use B5 paper with a page size of 176 mm x 250 mm. Element 2: Orientation
Specifies the print orientation on the page. INT(2) *PORTRAIT
*LANDSCAPE
The page has portrait orientation, with the long side on the left and right and with the short side on the top and bottom. The page has landscape orientation, with the short side on the left and right and with the long side on the top and bottom. Element 3: Scale to % normal size
Specifies the percentage of normal size used to scale the print. INT(2) If Element 4: Scale to page(s) wide or Element 5: Scale to page(s) tall are specified, this elementʹs radio button is not selected. *AUTO
10-400
A percentage adjustment is not specified. Specify a percentage adjustment to normal size. Element 4: Scale to page(s) wide
Specifies scaling in number of pages wide. INT(2) *AUTO
1-32767
Scale to pages is not specified. Specify the number of pages wide the spreadsheet is scaled to. Chapter 7 Commands
101
Element 5: Scale to page(s) tall
Specifies scaling in number of pages tall. INT(2) *AUTO
1-32767
Scale to pages is not specified. Specify the number of pages tall the spreadsheet is scaled to. Element 6: Print gridlines
Specifies if grid lines are printed. INT(2) *NO
*YES
Grid lines do not print. Grid lines are printed. Element 7: Print black and white
Specifies if printing is black and white. INT(2) *NO
*YES
Print in color. Print in black and white. Element 8: Print draft quality
Specifies if printing is draft quality. INT(2) *NO
*YES
Print with default print quality. Print with draft quality. Element 9: Print row and column headings
Specifies if row and column headings are printed. INT(2) *NO
*YES
Headings do not print. Headings are printed. Element 10: Print comments
Specifies comment printing. INT(2) *NONE
*DSP
*END
Comments do not print. Comments are printed as displayed. Comments are printed at the end. Element 11: Print order
Specifies the order in which pages are printed. INT(2) *DOWN
*OVER
Pages are printed down the spreadsheet, then over. Pages are printed across the spreadsheet, then down. Freeze pane (FREEZEPANE)
Specifies the number of rows at the top of the sheet and the number of columns at the left of the sheet that are frozen and remain visible when scrolling in the sheet. Single values
*NO
No data is frozen on the sheet. Element 1: Rows to freeze
Specifies the number of rows to freeze at the top of the sheet. INT(2) *CALC
*NONE
102
The number of rows to freeze is calculated based on the number of column heading and title rows specified. No rows are frozen at the top of the sheet. Excel-erator Programmer's Guide and Reference
Element 2: Columns to freeze
Specifies the number of columns to freeze at the left of the sheet. INT(2) *NONE
integer
No columns are frozen at the left of the sheet. The number of columns frozen. Priority (PRIORITY)
Specifies the priority of the message. Depending on the value specified, X‐Priority and/or importance MIME fields are included in the message headers. INT(2) *NONE
*HIGHEST
*HIGH
*NORMAL
*LOW
*LOWEST
*HIGHO
*NORMALO
*LOWO
X‐Priority and/or importance are not included in the message. X‐Priority 1, emulating Thunderbird. X‐Priority 2, emulating Thunderbird. X‐Priority 3, emulating Thunderbird. X‐Priority 4, emulating Thunderbird. X‐Priority 5, emulating Thunderbird. X‐Priority 1, importance high, emulating Outlook. X‐Priority 3, importance normal, emulating Outlook. X‐Priority 5, importance low, emulating Outlook. Sheet option (SHEETOPT)
Specifies sheet option information included in the spreadsheet. Note: Currently implemented for *OOXML only. Element 1: Right to left
Specifies right to left viewing direction. INT(2) *CONTEXT
*NO
*YES
Viewing direction is not specified in the worksheet and depends on the context (viewer). Viewing direction is left to right. Viewing direction is right to left. Target coded character set id (TRGCCSID)
Specifies the ASCII coded character set identifier (CCSID) that is used to map character data in the generated file. INT(4) Note: Only *BIFF4 supports this value and it is ignored unless TRANSFORM(*BIFF4) is specified. 1252
integer
The default Windows coded character set identifier is used. Specify the coded character set identifier to use. Source coded character set id (SRCCCSID)
Specifies the coded character set identifier (CCSID) used to create the file. INT(4) Note: Only *BIFF4 supports this value and it is ignored unless TRANSFORM(*BIFF4) is specified. *KBDTYPE
*SYSVAL
*JOBDFT
integer
The system determines the coded character set identifier value from the QKBDTYPE system value. The system determines the coded character set identifier value from the QCHRID system value. The system uses the current jobʹs default coded character set identifier. Specify the coded character set identifier to use. Chapter 7 Commands
103
To (distribution list) (TOUSRID)
Note: If this parameter is specified and the To (recipient) (TO) parameter is not specified, the entered value overrides the default value of the To (recipient) (TO) parameter. Specifies the Distribution list or network user to receive the email. CHAR(8), CHAR(8) Single values
*NONE
A network user or distribution list is not specified. Element 1: User ID
character-value
Specify the user ID (DEN) of the network user. CHAR(8) Element 2: Address
character-value
Specify the address (DGN) of the network user. CHAR(8) Examples
Example 1:
SNDFEXCEL
SNDF((CUSTOMER)) TO((biilg@acme.com))
This command converts file ʺCUSTOMERʺ into an Excel spreadsheet with the name ʺCUSTOMER.XLSʺ. The spreadsheet is sent as an email attachment to billg@acme.com. Example 2:
SNDFEXCEL
SNDF((INVOICE) (CUSTOMER))
TO((billg@acme.com))
This command converts files ʺINVOICEʺ and ʺCUSTOMERʺ into separate Excel spreadsheets with the names INVOICE.XLS and CUSTOMER.XLS respectively. These are sent as attachments to an email sent to billg@acme.com. Error messages
Parameter dependencies
XL17001
XL17002
XL17006
XL17007
XL17008
XL17009
XL17010
XL17011
XL17012
XL17014
XL17015
XL17016
SCV7001
SCV7002
XL17017
XL17018
A To (recipient) or a To (distribution list) must be specified. A To (recipient) or a To (distribution list) can be specified, but not both. When TRANSFORM(*BIFF4) is specified COLHDG(*COLHD1) and COLHDG(*COLHD1BLD) can not be specified. When PRTHEADER() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. When PRTFOOTER() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. When FONT() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. When COMMENT() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. When TRGCCSID() is specified TRANSFORM(*BIFF4) must be specified. When SRCCCSID() is specified TRANSFORM(*BIFF4) must be specified. When FILESHARE() is specified TRANSFORM(*BIFF8/*BIFF4) must be specified. When COLHDGFMT() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. When PALETTE() is specified TRANSFORM(*BIFF8/*BIFF4/*XMLSS/*OOXML) must be specified. CSV Separator character ʹ,ʹ required with TRANSFORM(*CSVRFC). CSV Separator character ʹ,ʹ required with TRANSFORM(*CSVRFCQ). When PAGESETUP() is specified TRANSFORM(*BIFF8/*XMLSS/*OOXML) must be specified. When FREEZEPANE() is specified TRANSFORM(*BIFF8/*XMLSS/*OOXML) must be specified. *ESCAPE messages
XL12017
104
Unable to send file Excel. Excel-erator Programmer's Guide and Reference
Verify Local SMTP (VFYLOCAL)
Where allowed to run: All environments (*ALL) Threadsafe: No The Verify Local SMTP (VFYLOCAL) command verifies or sets up SMTP on the local system. Details of the verification process are printed with the jobʹs spooled output in file XLLOG. Parameters
Keyword Description Choices Notes SETUP Make changes to system *NO, *YES, Y, N Optional, Positional 1 Make changes to system (SETUP)
Specifies the whether the command makes changes to the system. *NO
*YES
The command does not make changes to the local system. The command makes changes to the local system. Examples
Example 1:
VFYLOCAL
SETUP(*NO)
This command verifies that SMTP is set up correctly on the local system. Example 2:
VFYLOCAL
SETUP(*YES)
This command sets up SMTP on the local system. Error messages
*ESCAPE messages
MSU5037
SMTP verification/set up failed Chapter 7 Commands
105
Verify Mailhub Server (VFYMAILHUB)
Where allowed to run: All environments (*ALL) Threadsafe: No The Verify Mailhub Server (VFYMAILHUB) command verifies or sets up a forwarding mailhub server for use by the local system. Details of the verification process are printed with the jobʹs spooled output in file XLLOG. The command is intended for initial configuration of a system. If a mailhub server and/or host logon information for it have previously been configured, this command cannot be used to modify the system. You can remove a previously configured forwarding mail hub server by running: CHGSMTPA
FWDHUBSVR(*NONE)
You can remove previously configured host logon information by running: RMVSMTPLE TYPE(*HOSTAUTH) HOSTNAME('configured_host_name')
Note: When prompting, input fields can be expanded by typing an ampersand (&) in the first position of the field followed by a blank, and pressing enter. Parameters
Keyword Description Choices RMTSYS Remote system Character value, *MAILHUB, *INTNETADR Notes Optional INTNETADR Remote internet address Character value, *RMTSYS, *MAILHUB Optional AUTHUSRNAM Authentication username Character value, *NONE Optional AUTHPWD Authentication password Character value Optional SETUP Make changes to system *YES, *NO, Y, N Optional Remote system (RMTSYS)
Specifies the remote system name of the host with which the Verify Mailhub Server operation takes place. To be successful, the name must be valid, and the remote system must be able to communicate with the local system. *MAILHUB
*INTNETADR
character-value
The name of the configured SMTP forwarding mailhub server is used. The INTNETADR parameter is used. Specify the remote system name to use. Remote internet address (INTNETADR)
Specifies the remote internet address. The internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address. If the internet address is entered from a command line, enclose the address in apostrophes. *RMTSYS
*MAILHUB
character-value
The internet address of the specified remote system is used. The internet address of the configured SMTP forwarding mailhub server is used. Specify the internet address to use. Authentication username (AUTHUSRNAM)
Specifies the user name used to authenticate with the remote system. CHAR(80) 106
Excel-erator Programmer's Guide and Reference
Valid characters are case sensitive and include all alpha‐numeric characters (a‐z, A‐Z, and 0‐9), and the following special characters: characters: .,!#$%&*+‐/:;=@?_~^. *NONE
character-value
Authentication is not performed. Specify the user name to send to the remote system for authentication. Authentication password (AUTHPWD)
Specifies the password used to authenticate with the remote system. CHAR(128) Valid characters are case sensitive and include all alpha‐numeric characters (a‐z, A‐Z, and 0‐9), and the following special characters: characters: .,!#$%&*+‐/:;=@?_~^. character-value
Specify the password to send to the remote system for authentication. Make changes to system (SETUP)
Specifies the whether the command makes changes to the system. *NO
*YES
The command does not make changes to the local system. The command makes changes to the local system. Examples
Example 1:
VFYMAILHUB
RMTSYS(*MAILHUB) SETUP(*NO)
Command verifies that the currently configured forwarding mailhub server is set up and operating correctly. Example 2:
VFYMAILHUB
RMTSYS(sys1.widget.com)
INTNETADR(192.168.1.2) SETUP(*YES)
This command sets up sys1.widget.com at address 192.168.1.2 as the forwarding mailhub server for this IBM i. Error messages
Parameter dependencies
MSU7011
RMTSYS(*INTNETADR) and INTNETADR(*RMTSYS) are mutually exclusive. *ESCAPE messages
MSU5165
Mailhub server verification/set up failed Chapter 7 Commands
107
Verify Mail Router (VFYROUTER)
Where allowed to run: All environments (*ALL) Threadsafe: No Note: THIS COMMAND HAS BEEN SUPERCEDED AND WILL BE REMOVED IN A FUTURE RELEASE. Use Verify Mailhub Server (VFYMAILHUB) instead. The Verify Mail Router (VFYROUTER) command verifies or sets up a remote mail router for use by the local system. Note: If a mail router has previously been configured, this command cannot be used to change it. Details of the verification process are printed with the jobʹs spooled output in file XLLOG. Parameters
Keyword Description Choices Notes RMTSYS Remote system Character value, *ROUTER, *INTNETADR Optional, Positional 1 INTNETADR Remote internet address Character value, *RMTSYS, *ROUTER Optional, Positional 2 SETUP Make changes to system *YES, *NO, Y, N Optional, Positional 3 Remote system (RMTSYS)
Specifies the remote system name of the host with which the Verify Mail Router operation takes place. To be successful, the name must be valid, and the remote system must be able to communicate with the local system. *ROUTER
*INTNETADR
character-value
The name of the configured SMTP mail router is used. The INTNETADR parameter is used. Specify the remote system name to use. Remote internet address (INTNETADR)
Specifies the remote internet address. The internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address. If the internet address is entered from a command line, enclose the address in apostrophes. *RMTSYS
*ROUTER
character-value
The internet address of the specified remote system is used. The internet address of the configured SMTP mail router is used. Specify the internet address to use. Make changes to system (SETUP)
Specifies the whether the command makes changes to the system. *NO
*YES
The command does not make changes to the local system. The command makes changes to the local system. Examples
Example 1:
VFYROUTER
108
RMTSYS(*ROUTER) SETUP(*NO)
Excel-erator Programmer's Guide and Reference
Command verifies that the currently configured mail router is set up and operating correctly. Example 2:
VFYROUTER
RMTSYS(sys1.widget.com)
INTNETADR(192.168.1.2) SETUP(*YES)
This command sets up sys1.widget.com at address 192.168.1.2 as the mail router for this IBM i. Error messages
Parameter dependencies
MSU7011
RMTSYS(*INTNETADR) and INTNETADR(*RMTSYS) are mutually exclusive. *ESCAPE messages
MSU5139
Mail router verification/set up failed Chapter 7 Commands
109
Chapter 8 Trouble-Shooting
What's In This Chapter
This chapter provides information and procedures useful for correcting or reporting Excel‐erator problems. The chapter: 





Describes general trouble‐shooting. Describes software installation problems. Describes Excel file problems. Describes general mail delivery problems. Describes MSF specific delivery problems. Describes SMTP specific delivery problems. General Trouble-Shooting
If a command from Excel‐erator fails to run to completion or if the results you receive are different from those expected, perform these items: 



Check the detailed messages in your job log: 1. Run the DSPJOBLOG command. 2. Press F10 to display detailed messages. 3. Locate the messages related to the error. 4. Place your cursor on each message in turn and press F1. 5. Take any corrective actions suggested by the messages. Download the current cumulative PTF package from www.gumbo.com. Check the bottom of the PTF page at www.gumbo.com for IBM PTFs that may be required. Review the detailed trouble shooting procedures in this chapter for solutions related to your problem. If you are unable to correct the problem, prepare a problem report and contact your service provider. Software Installation Problems
This section describes problems, causes, and solutions specific to software installation. 
Installation Generates ʺDirectory not registered. (C G)ʺ Symptom
Cause
Solution

During installation inquiry message id CPA3DE4 ʺDirectory not registered. (C G)ʺ is issued. IBM i has lost the relationship between the product and the directory and hence the message. You can safely take a ʺGʺ to this message. You will receive the message three or four times. Installation Fails Symptom
Cause
Solution
Installation fails and diagnostic message id CPF9898 ʺUnable to clear old release. Is the software being used?ʺ appears in the job log. Or, when the installation verification option is run, verification fails with diagnostic message id CPD0C2E appearing in the job log. This usually arises from attempting to install a new release over an old release while objects in the old release are in use. End the jobs that are holding locks on (using) objects from the old release and perform the installation Chapter 8 Trouble-Shooting
111
again. 
Installation Fails or Installation Verification Fails Symptom
Cause
Solution
Installation or installation verification fails and messages in the job log do not help in recovering. The software is not installed correctly or the installation is damaged. This can be caused for a variety of reasons including renaming of libraries, directories, or objects that make up the product. Get the system to a stable consistent state by completely removing the product then re‐installing it by performing the following: 1. Check the system library list by running: DSPSYSVAL SYSVAL(QSYSLIBL)
Note: If XLERATOR is present, remove it with WRKSYSVAL and IPL the system. 2.
Delete the licensed program by running: DLTLICPGM LICPGM(2A55XL1) RLS(*ALL) OPTION(*ALL)
Note: It is okay if this fails with diagnostic CPD3D91 ʺProduct 2A55XL1 option *ALL release *ALL not installed.ʺ 3.
Delete the productʹs library by running: DLTLIB LIB(XLERATOR)
Note: It is okay if this fails with escape CPF2110 ʺLibrary XLERATOR not found.ʺ 4.
Delete the productʹs directories by running: RMVDIR DIR('/Gumbo/ProdData/2A55XL1') SUBTREE(*ALL) RMVLNK(*YES)
Note: It is okay if this fails with escape CPFA0A9 ʺObject not found. ...ʺ. If there are no other GUMBO products installed: RMVDIR
RMVDIR
DIR('/Gumbo/ProdData')
DIR('/Gumbo')
Note: It is okay if these fail with escape CPFA0A9 ʺObject not found. ...ʺ. 5.
Rebuild IBM iʹs internal licensed program information by running: CALL PGM(QSYS/QSZRECOV)
Note: This takes several minutes depending on machine size. 6.
7.
Install the product according to the instructions in the Installation chapter. Enter your authorization code. XLS File Problems
This section describes problems, causes, and solutions specific to Excel Format (XLS) files. 
Large Character Fields Are Truncated Symptom
Cause
Solution

Currency Symbol Not Present In Cell Symptom
Cause
Solution
112
The file is generated and displays without error however, some large character fields are truncated. *BIFF4 imposes a 255 byte limit on the length of character fields. Switch to *BIFF8, which lifts the limit on field size. Data in a cell should be presented with a currency symbol but is not. The underlying database field doe not specify an edit code or edit word specifying a currency symbol. Change the field definition in the physical file to specify and edit code by adding EDTCDE(J ʹ$ʹ) OR EDTCDE(J *). Alternately if you donʹt have control over the source for the file, draw a logical that adds the edit code. Excel-erator Programmer's Guide and Reference
General Mail Delivery Problems
This section describes common problems, causes, and solutions for general mail delivery problems. They are listed roughly in the order in which you should proceed. During general mail delivery trouble shooting you should send tests to yourself. Once this works properly, you can move on. The bulk of the entries in this section are derived from trouble shooting performed by or with customers and in some sense presume that you have an ʺaverageʺ installation. The ʺaverageʺ installation is IBM i connected to a LAN with the post office (a.k.a. mailhub) on a LAN attached PC running Exchange or Domino, with a connection to the internet at large. At the ʺaverageʺ installation this is the first application to generate email from IBM i. Some of the entries in this section may not apply to your situation. 
System Mailhub Configuration Is Unknown Symptom
Cause
Solution

The name of the configured mailhub is unknown. You did not originally configure the system for email delivery. Prompt the CHGSMTPA command and inspect the Forwarding mailhub server (FWDHUBSVR) parameter. If the value is *NONE, a mailhub is not configured. Otherwise, the name of the mailhub is shown. Source Of Problem Is Unknown Symptom
Cause
Solution
The send operation runs to completion but no mail arrives. The problem may be with the mailhub or with IBM i, but the source is unknown. Run PINGMAIL to generate a test message to your email address and directly deliver it to the mailhub by passing IBM iʹs mail machinery entirely: Note: Substitute the name of your mailhub for the value ʺmailhub_serverʺ and substitute your email address for the value ʺyou@domain.comʺ in the following command. PINGMAIL RMTSYS(mailhub_server) SMTPNAME(you@domain.com)
If you receive the test message, the mailhub is working correctly and an IBM i issue is indicated. In particular, if the rest of the entries in this section do not correct the problem, you may have a DNS issue. If you do not receive the test message then there is a problem with the mailhub. You may be able to get an indication of the problem by reviewing the SMTP conversation, which appears in your joblog. Run DSPJOBLOG, press F10 and page back for details. 
IBM i Servers Are Down Symptom
Cause
Solution
The send operation runs to completion but no mail arrives. The IBM i servers responsible for mail delivery may be down, particularly if IBM i has been IPLed. Rerun VFYLOCAL to verify that all local servers are up and running: VFYLOCAL SETUP(*NO)
If local verification fails, run: VFYLOCAL SETUP(*YES)

Mailhub Is Not Processing Mail Symptom
Cause
The send operation runs to completion but no mail arrives. The mailhub responsible for mail delivery may be down, or not accepting mail from IBM i. Chapter 8 Trouble-Shooting
113
Solution
Rerun VFYMAILHUB to verify that the mailhub is up and running: VFYMAILHUB SETUP(*NO)
If mailhub verification fails, run: VFYMAILHUB SETUP(*YES)

Mailhub Refuses Mail with ʺFunnyʺ Originator Address Symptom
Cause
Solution
The send operation runs to completion but no mail arrives. Or mail arrives for some users but not all users, for example for all but AOL accounts. An email address is not assigned to your directory entry and the mailhub does not like the ʺfunnyʺ address IBM i generates for the originatorʹs address. Assign your email address to your system distribution directory entry: (assume for this example that your ʺUser ID and Addressʺ are ʺBILLG S1234567ʺ and you ʺrealʺ email address is ʺbillg@acme.comʺ) CHGDIRE USRID(BILLG S1234567)
MSFSRVLVL(*SYSMS) PREFADR(*SMTP)
USRDFNFLD((SMTPAUSRID SMTP 'billg')
(SMTPDMN SMTP 'acme.com'))
Note: If you are a local Domino for IBM i user substitute MSFSRVLVL(*DOMINO) for MSFSRVLVL(*SYSMS). 
SMTP Servers Require Reinitialization Symptom
Cause
Solution

The send operation runs to completion but no mail arrives. IBM iʹs SMTP servers may need to reinitialize. This is undocumented but our experience and discussions with IBM iʹs SMTP architect confirm this. Reinitialize IBM iʹs SMTP servers: INZLOCAL SMTP(*YES) SMTPPURGE(*NO) MSF(*NO) MSFPURGE(*NO)
SMTP Servers Are Clogged With Junk Symptom
Cause
Solution
The send operation runs to completion but no mail arrives. IBM iʹs SMTP server may contain dead letters or other junk that it cannot deliver. This can be the result of previous attempts to set up mail on the system. Clean out IBM iʹs SMTP server: Note: Only perform this procedure if you are sure there is no valid deliverable mail in the SMTP server. Note: This procedure should be required at most once per system during initial set up. INZLOCAL SMTP(*YES) SMTPPURGE(*YES) MSF(*YES) MSFPURGE(*YES)

Mail Server Framework Is Reporting Errors Symptom
Cause
114
The send operation runs to completion but no mail arrives. IBM iʹs Mail Server Framework jobs may be unable to process mail and are reporting errors. Excel-erator Programmer's Guide and Reference
Solution

Review job logs for the Mail Server Framework jobs: 1. Work with active jobs by running the following command: WRKACTJOB
2. Page down to the QSYSWRK subsystem. 3. Locate the job or jobs with the name QMSF and repeat the following steps for each job. 4. Display the job by using option 5 and pressing enter. 5. Display the job log by selecting option 10 and pressing enter. 6. Display detailed messages by pressing F10. 7. You should see a job started (CPF1124) and job submitted (CPI1125) message. If there are no other messages, the Mail Server Framework is not reporting errors. (End of procedure). 8. Display detailed information for each additional message by placing your cursor on the message and pressing F1. 9. Take any corrective action specified in the messages. 10. See the MSF Specific Delivery Problems section of this chapter. Mail Server Framework Is Ending Abnormally Symptom
Cause
Solution
The send operation runs to completion but no mail arrives. IBM iʹs Mail Server Framework jobs may be unable to process mail and are ending abnormally. Review job logs for the Mail Server Framework jobs: 1. Locate job logs for Mail Server Framework jobs that have ended by running the following command: WRKSPLF SELECT(QMSF)
If there are no spooled output files, the Mail Server Framework is not ending abnormally (end of procedure). 2.
3.
4.
5.
6.
7.
8.

Page down to the end of the list of spooled files. Display the date and time of the spooled files by pressing F11. If there are no recent spooled files, the Mail Server Framework is not ending abnormally (end of procedure). For each recent job log repeat the following steps: Display the job log by using option 5 and pressing enter. Review the job log for diagnostic and escape messages. Take any corrective action specified in the messages. See the MSF Specific Delivery Problems section of this chapter. SMTP Servers Are Reporting Errors Symptom
Cause
Solution
The send operation runs to completion but no mail arrives. IBM iʹs SMTP server jobs may be unable to process mail and are reporting errors. Review job logs for the SMTP server jobs: 1. Work with active jobs by running the following command: WRKACTJOB
2. Page down to the QSYSWRK subsystem. 3. Locate the 4 SMTP server jobs with names that start with QTSMTP*. Repeat the following steps for each job. 4. Display the job by using option 5 and pressing enter. 5. Display the job log by selecting option 10 and pressing enter. 6. Display detailed messages by pressing F10. 7. You should see a job started (CPF1124) and job submitted (CPI1125) message. If there are no other messages, the Mail Server Framework is not reporting errors. (End of procedure). 8. Display detailed information for each additional message by placing your cursor on the message and pressing F1. 9. Take any corrective action specified in the messages. 10. See the SMTP Problems section of this chapter. Chapter 8 Trouble-Shooting
115

SMTP Servers Are Ending Abnormally Symptom
Cause
Solution
The send operation runs to completion but no mail arrives. IBM iʹs SMTP server jobs may be unable to process mail and are ending abnormally. Review job logs for the SMTP server jobs: 1. Locate job logs for SMTP server jobs that have ended by running the following command: WRKSPLF SELECT(QTCP)
If there are no spooled output files, the SMTP server jobs are not ending abnormally (end of procedure). 2.
3.
4.
5.
6.
7.
8.
Page down to the end of the list of spooled files. Display the date and time of the spooled files by pressing F11. If there are no recent spooled files, the SMTP server jobs are not ending abnormally (end of procedure). For each recent job log repeat the following steps: Display the job log by using option 5 and pressing enter. Review the job log for diagnostic and escape messages. Take any corrective action specified in the messages. See the SMTP Problems section of this chapter. MSF Specific Delivery Problems
This section describes problems, causes, and solutions specific to IBM iʹs Mail Server Framework. 
MSF Job Log Contains QTCPTMM/ATTABOX Messages Symptom
Cause
Solution

A QMSF job is complaining about a directory such as QTCPTMM/ATTABOX. IBM iʹs MSF jobs depend on specific directories in the Integrated File System which are added by installing the TCP/IP Utilities and may have been deleted. Check the existence of the TCP/IP related directories an reinstall them if they are missing by: 1. Run the WRKLNK command and locate the QTCPTMM directory. 2. Display QTCPTMMʹs contents using option 5. 3. Verify that subdirectories ATTABOX, ENCODE, MAIL, SMTPBOX and TMP exist. 4. If directories are missing continue with this procedure otherwise end of procedure. 5. Use the DLTLICPGM command to remove the TCP/IP Utilities. 6. Use the RSTLICPGM command to reinstall the TCP/IP Utilities. MSF Job Log Contains ʺSystem storage threshold exceededʺ Message Symptom
Cause
Solution
A QMSF job complains that ʺSystem storage threshold exceededʺ. IBM iʹs MSF jobs stop processing mail when amount of disk space used rises above a set percentage. IBM i ships with this value set to 90%. Either free disk space by deleting unused items or bump the threshold value with this procedure: 1. Run the STRSST command and select option 3 Work with disk units. 2. Select option 2 Work with disk configuration. 3. Select option 3 Work with ASP threshold. 4. Use 1=Select for the appropriate ASP (usually ASP 1). 5. Press F1=Help to review help for the Change Storage Threshold display. 6. Change the ASP threshold to 95% or a comfortable value for your installation. SMTP Specific Delivery Problems
This section describes problems, causes, and solutions specific to IBM iʹs SMTP servers. 
116
SMTP Retries Set To Zero Excel-erator Programmer's Guide and Reference
Symptom
Cause
Solution

Multiple Garbled Email Messages Arrive Symptom
Cause
Solution

The send operation runs to completion but no mail arrives, or mail arrives for a while then stops until the next IPL. The mailhub is periodically slow or unavailable and IBM iʹs SMTP attributes for retries are set too low or set to zero. Increase the retry values to give the mailhub more chances at fielding the incoming mail: 1. Prompt the CHGSMTPA command. 2. Increase the number of retries for the retries by minute parameter. 3. Increase the number of retries for the retries by day parameter. 4. Press enter. Multiple messages arrive for a send operation and the messages are garbled. IBM iʹs SMTP is splitting the messages. Turn off message splitting entirely by changing the POP attributes: CHGPOPA
MSGSPLIT(*NOMAX)
Time On Mail Is Incorrect Symptom
Cause
Solution
Mail delivers but contains the wrong time. IBM iʹs QTIMZON system value is not set. See Manual Mail Set Up Steps section of the Set Up chapter for instructions to correct this value. For related information see the System management > Time management topic in the IBM i Information Center at http://publib.boulder.ibm.com/eserver/ibmi.html. Chapter 8 Trouble-Shooting
117
Appendix A Process Descriptions
What's In This Appendix
This appendix provides detailed descriptions of the processing performed by Excel‐eratorʹs mail set up and verification programs. In highly secure environments, it may be against policy to allow third party software to change your system. If this is your situation, you can perform these steps manually. The appendix details: 



Processing Performed During SMTP Verification Processing Performed During SMTP Set Up Processing Performed During Mailhub Verification Processing Performed During Mailhub Set Up SMTP Verification Process
The following verification steps are performed by the Verify Local SMTP (VFYLOCAL) command when SETUP(*NO) is specified. Note: No changes are made to your system during verification. 
Verify that TCP Utilities have been installed on the system. The system is checked to insure that library QTCP exists. If the library is found then the TCP Connectivity Utilities have been installed on the system. 
Verify that the SMTP distribution queues are present. The system is checked for the existence of QSMTPQ distribution queue. 

Verify that a host and domain name have been configured for the system. o If the host name is blank, verification fails. o If the domain name is blank, verification fails. Verify that the system distribution directory is searchable. A search is attempted on the system distribution directory. 
Verify that the IBM i Mail Server is active. The system is checked for an active job with the job name QMSF. If one or more QMSF jobs are active then the Mail Server is active. 
Verify that TCP is active. The system is checked for an active job with the job name QTCPWRK (before V6 JOB QTCPIP). If job is active then TCP is active. 
Verify that TCP loopback is operating correctly. Appendix A Process Descriptions
119
The TCP interfaces are searched to locate the *LOOPBACK IP address. The *LOOPBACK interface is started if it is not active and its IP address is PINGed to verify that TCP is operating correctly. If the *LOOPBACK interface is not found, verification fails. If the *LOOPBACK interface is not active and cannot be started, verification fails. o If the *LOOPBACK interface cannot be PINGed, verification fails. Verify that a TCP interface is defined. o
o

The TCP interfaces are searched to locate one or more IP addresses (excluding *LOOPBACK). 
o If no interfaces are found, verification fails. Verify that active TCP interfaces are reachable. The TCP interfaces are searched to locate one or more IP addresses (excluding *LOOPBACK). Each interface is contacted (PINGed) to verify the connection. 
o If an interface is not active, verification fails. o If an interface cannot be contacted, verification fails. Verify that the SMTP server is active. The system is checked for an active job with the job name QTSMTPSRVR or QTSMTPSRVD. If either job is active then the SMTP server is active. 
Verify that this hostʹs IP address can be reached by SMTP. o Retrieve the host and domain names for this system. If the host name is blank, verification fails. o
Verify TCP/IP connection to the host name. If the host is contacted, verification is complete and no further processing is performed. o
Verify TCP/IP connection to the host.domain name. If the host.domain name cannot be contacted, verification fails. 
Verify that message splitting has been turned off. The current setting cannot be retrieved so no test is performed and it is assumed that splitting has not been turned off yet. After all tests are completed, a message summarizing the results is issued. 120
Excel-erator Programmer's Guide and Reference
SMTP Set Up Process
The following set up work is performed by the Verify Local SMTP (VFYLOCAL) command when SETUP(*YES) is specified. 

If the TCP utilities have not been installed on the system. o Manual intervention is required to install the utilities. Automatic set up cannot perform the installation. If QSMTPQ distribution queue is not found. o Create the distribution queue using the Add Distribution Queue command: ADDDSTQ


If a host or domain name have not been configured. o Manual intervention is required to configure a host and domain name. Use option 12 (Change local domain and host names) of the Configure TCP/IP (CFGTCP) command. Automatic set up cannot perform the change. If the system distribution directory entry cannot be searched. o The directory is changed to allow searches using the Change System Directory Attributes command: CHGSYSDIRA

DSTQ(QSMTPQ) RMTLOCNAME(TCPIPLOC)
DSTQTYPE(*RPDS)
ALWSCH(*YES)
If the IBM i Mail Server is not active. o Start the Mail Server using the STRMSF command: STRMSF

If TCP is not active. o Start TCP using the STRTCP command: STRTCP

If TCP loopback is not operating correctly. o If missing, *LOOPBACK interface is added using command: ADDTCPIFC
o
INTNETADR('127.0.0.1') LIND(*LOOPBACK) +
SUBNETMASK('255.0.0.0') MTU(576)
If loopback PING fails: Manual intervention is required to correct the problem, which is beyond the scope of set up. 
If no TCP interfaces are found. Manual operation is required to add an interface using the ADDTCPIFC command. Appendix A Process Descriptions
121

If a TCP interface cannot be contacted. Manual operation is required to correct the problem. If the interface cannot be contacted because it is not active, start the interface using the STRTCPIFC command. 
If the SMTP server is not active. o Start the SMTP server using the STRTCPSVR command: STRTCPSVR

SERVER(*SMTP)
If the hostʹs IP address cannot be reached by SMTP. o If system is using a remote name server, set up fails. Manual operation required. Contact the remote name serverʹs administrator to add this systemʹs host name. o
If multiple TCP interfaces are found, set up fails. Manual operation required. Add this systemʹs name to IBM iʹs host table using the ADDTCPHTE command. o
If no TCP interfaces are found, set up fails. Manual operation required. Add a TCP interface using the ADDTCPIFC command. o
An entry is added for this host using the Add TCP Host Table Entry command: ADDTCPHTE

INTNETADR(&INTERNET) HOSTNAME((&HOST)) +
TEXT('Entry Added By Gumbo Auto TCP/IP +
Config')
If message splitting has not been turned off. o Message splitting is turned off The POP attributes are changed: CHGPOPA
MSGSPLIT(*NOMAX)
After all steps are completed, a message summarizing the results is issued. Mailhub Verification Process
The following verification steps are performed by the Verify Mail Router (VFYMAILHUB) command when SETUP(*NO) is specified. Note: No changes are made to your system during verification. 
122
Verify that TCP is active. Excel-erator Programmer's Guide and Reference
The system is checked for an active job with the job name QTCPWRK (before V6 JOB QTCPIP). If job is active then TCP is active. 
Resolve system names and internet addresses for command parameters and current mail hub server. o Verify domain name server. If a domain name server is configured, it is tested to insure that it is responding. If it does not respond, verification fails. o
o
Retrieve currently configured mail hub server name and IP Resolve internet address parameter. If a special value was specified, it is resolved. If it can not be resolved, verification fails. o
Resolve remote system parameter. If a special value was specified, it is resolved. If it can not be resolved, verification fails. 
Edit the resulting names and IPs for conflicts. o Edit remote system and internet address IP. If the IP of the remote system is different from the internet address, verification fails. o
Edit remote system and internet address names. If the name of the internet address is different from the remote system name, verification fails. o
Edit current mail hub server and internet address IP. If the IP of the current mail hub server is different from the internet address, verification fails. 
Verify that the internet address is responding. The internet address is PINGed to insure that it is reachable and responding. If it is not, verification fails. 
Verify that the internet address is accepting SMTP mail. The internet address is tested to insure that it is accepting SMTP mail from this system. If it is not, verification fails. Appendix A Process Descriptions
123

Verify that remote systemʹs IP can be resolved. If an IP cannot be resolved, verification fails. 
Verify that the mail hub server is configured. If the remote system is not configured as the mail hub server, verification fails. After all tests are completed, a message summarizing the results is issued. Mailhub Set Up Process
The following set up work is performed by the Verify Mail Router (VFYMAILHUB) command when SETUP(*YES) is specified. 
If TCP is not active. o Start TCP using the STRTCP command: STRTCP

If a mail hub server is currently configured. SETUP(*YES) is suppressed. No changes will be made to the system. VFYMAILHUB will be processed as SETUP(*NO). To avoid suppression, remove the current mail hub server by running: CHGSMTPA

FWDHUBSVR(*NONE)
If an entry currently exists on the SMTP *HOSTAUTH list for the remote system. SETUP(*YES) is suppressed. No changes will be made to the system. VFYMAILHUB will be processed as SETUP(*NO). To avoid suppression, remove the current SMTP *HOSTAUTH list entry by running: RMVSMTPLE TYPE(*HOSTAUTH) HOSTNAME('configured_host_name')

If system name and internet address resolution fails. o If a domain name server is configured but not responding. Manual intervention required. Either insure that the configured domain name server is available or remove the domain name server from IBM iʹs configuration using option 13 of the CFGTCP menu. o
If the internet address parameter cannot be resolved. Manual intervention required to correct the internet address parameter. o
If the remote system parameter cannot be resolved. Manual intervention required to correct the remote system parameter. 124
Excel-erator Programmer's Guide and Reference

Edit the resolved names and IPs for conflicts. o If the remote system and internet address IPs are different. Manual intervention required to correct the parameters. o
If the remote system and internet address names are different. Manual intervention required to correct the parameters. o
If the current mail hub server and internet address IPs are different. Manual intervention required. Either correct the parameters or remove the currently configured mail hub server by running the following command: CHGSMTPA

FWDHUBSVR(*NONE)
If the internet address is not responding. Manual intervention required. Either correct the internet address or make the system at that address ready. 
If the internet address is not accepting SMTP mail. Manual intervention required. Either correct the internet address, or contact the systemʹs administrator and request that the system accept SMTP from IBM i. The words you use to request this differ depending on the software running on the remote system: For Microsoftʹs Exchange Server request that the ʺInternet Mail Connectorʺ be configured and started. Then request that ʺSMTP forwardingʺ be enabled for your systemʹs IP. o For Lotusʹ cc:Mail request that the ʺLink to SMTPʺ be configured and started. o For all others request that the ʺSMTP gatewayʺ be configured and started. If the remote systemʹs IP cannot be resolved. o

Add an entry using the Add TCP/IP Host Table Entry (ADDTCPHTE) command: ADDTCPHTE

INTNETADR(&INTNETADR) HOSTNAME((&RMTSYS)) +
TEXT('Mailhub added by Gumbo +
VFYMAILHUB command')
If authentication username and password are included. Add the authentication information to the SMTP *HOSTAUTH list: ADDSMTPLE

TYPE(*HOSTAUTH) HOSTNAME(&RMTSYS) +
USERNAME(&AUTHUSRNAM) PASSWORD(&AUTHPWD)
If the mail hub server is not configured. Configure the mail hub server using the Change SMTP Attributes (CHGSMTPA) command: Appendix A Process Descriptions
125
CHGSMTPA
FWDHUBSVR(&RMTSYS)
After all steps are completed, a message summarizing the results is issued. 126
Excel-erator Programmer's Guide and Reference
Appendix B Notices
Copyrights
© Copyright Gumbo Software, Inc. 2001, 2017. All Rights Reserved. Portions of this software are used with permission and: 












Copyright © 1991‐2, RSA Data Security, Inc. All rights reserved. Copyright © April 29, 1997 Kalle Kaukonen. All Rights Reserved. Copyright © 1995‐1997 Peter Mattis, Spencer Kimball and Josh MacDonald Copyright © 1998‐1999, 2000‐2001 Tim Janik and Red Hat, Inc. Copyright © 2000 Konstantin Chuguev. All rights reserved. Copyright © 2002‐2006 Jody Goldberg (jody@gnome.org) Copyright © 1998‐2000 Carnegie Mellon University. All rights reserved. Copyright © 2002, 2003, 2004 Simon Josefsson Copyright © 1998‐2006 The OpenSSL Project. All rights reserved. Copyright © 1995‐1998 Eric Young (eay@cryptsoft.com) All rights reserved. Copyright © 1998‐2003 Daniel Veillard. All Rights Reserved. Copyright © 1995‐1998 Jean‐loup Gailly Copyright © 1995‐1998 Mark Adler For additional information, see file XLERATOR/COPYRIGHT. Appendix B Notices
127
Appendix C License Agreement
License
Gumbo Software, Inc. grants to the purchaser, permanent license to use Excel‐erator on the specified IBM system serial number. For system wide licenses the grant is specific to a processor group and covers the system as a whole. For partition licenses the grant is specific to a partition number (ID) and maximum processing capacity. This license is not transferable and not exclusive. Warranty
Gumbo Software, Inc. makes no warranty, either expressed or implied, with respect to Excel‐erator, its merchantability or its fitness for any particular purpose. Excel‐erator software and documentation are provided on an ʺAS ISʺ basis. Liability
Gumbo Software, Inc. assumes no responsibility for the use of Excel‐erator. Purchaser agrees that Gumbo Software, Inc.ʹs liability under any circumstances shall not exceed the charges paid by purchaser. Updates
Gumbo Software, Inc. may from time to time update Excel‐erator to correct defects or add enhancements. Purchaser will receive updates for a period of one year from date of purchase. Rev: 2016/08/25 128
Excel-erator Programmer's Guide and Reference
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising