Carbonite Server Backup
Agent for IBM i
Version 6.21.2702
Release Notes, October 12, 2017
______________________________________________________________________
Contents
1	Overview
1.1	Release History
1.2	Supported Platforms
2	NEW FEATURES
2.1	New Feature in Version 6.21
2.2	New Features in Version 6.20
3	INSTALLATION NOTES
3.1	Installation Requirements
3.2	Licensing
3.3	Install/Upgrade
4	FIXES and KNOWN ISSUES
4.1	Fixes
4.2	Known Issues
5	PRODUCT SUPPORT
5.1	Technical Support
5.2	Product Updates
5.3	Documentation
______________________________________________________________________
1	Overview
This document contains release notes for IBM i Agent version 6.21.
This release is supported with Director version 8.3xx and later.
1.1	Release History
Version 6.21.2702, May 1, 2015
Version 6.20.2618, March 14, 2011 
1.2	Supported Platforms
The Agent is supported on IBM i v7r2, v7r1, v6r1, v5r4, and v5r3 operating systems.
2	NEW FEATURES
2.1	New Feature in Version 6.21
•	The Agent now supports IBM i v7r2.
2.2	New Features in Version 6.20
•	This version of the IBM i Agent contains an updated installation kit with IASP (Independent Auxiliary Storage Pool) functionality.
•	Improvements to the TCP/IP protocol and the QUSRSYS library further improve data integrity and the speed of data transmissions.
•	Temporary user-defined file system (UDFS) IFS file exclusions improve performance by reducing disk operations through the removal of temporary objects. 
•	The block special file (*BLKSF) object is now excluded from the temporary user-defined file system (UDFS).
•	You can rename an auto job.
•	Improvements to the Integrated File System (IFS) improve the performance of backups and restores.
•	When restoring multi-member files, you can choose to restore an individual file.
3	INSTALLATION NOTES
3.1	Installation Requirements
Before installing the Agent, we recommended installing the latest cumulative, hyper and group PTFs (Program Temporary Fixes) from IBM.
3.2	Licensing
Agent licenses are distributed automatically when the Agent connects to a vault. To back up and restore data to or from a vault, you need a valid account, username and password. Contact your service provider to obtain the required information.
3.3	Install/Upgrade
The IBMIAGENT file is first downloaded to a PC from the service provider's website. This file is then sent via FTP to the IBM i, in a library of the user's choosing. 
Note: You cannot FTP the file directly to the IBM i when it is in ZIP format. You must download it to a PC first, unzip it, and then copy it to the IBM i.
Alternatively, you can download a CD image file from your service provider web site, burn these to a CD (in Windows), and then use that CD on the IBM i to install the Agent software.
IBM i Agent 6.21 supports upgrades from IBM i Agent versions 5.32 and later.
For more information, see the IBM i Agent User Guide.
4	FIXES and KNOWN ISSUES
4.1	Fixes 
4.1.1	Fixes in Version 6.21
During a backup on an independent ASP, many errors occurred. The backup would sometimes hang and the job could not be killed. (28210, 22411)
IFS delta backups changed attributes of unchanged objects, causing excessive journal entries to be created. A configuration change is now available that prevents IFS delta backups from causing excessive journaling for a specific job. You can apply this option to both ad-hoc and scheduled backups for a job, or only to scheduled backups for a job.
To apply the configuration change to both ad-hoc and scheduled backups for a job, edit the job vvc file:
1. Open "/buagent/<jobname>.vvc" in edit mode.
2. Add the line "Last_Access_Time_Fix = FALSE" under the line 
   "Include = "
To apply the change to only scheduled backups for a job (without applying the change to ad-hoc backups for the job), edit the schedule command:
1. Enter the following command: WRKJOBSCDE
2. Change (opt 2) to the schedule job.
3. Modify the command by adding '/LATFIX= NO' into the PARM()
(27519)
When an exclusion was specified in a backup job, the Agent filtered out members from the backup and only backed up one member on a physical file with many members. (25795)
Backup jobs no longer fail with pointer errors. (25337)
When the Agent backed up an object that was locked at the start of a backup process, the backup was marked as suspect after vault maintenance. The Agent no longer backs up files that are locked at the start of a backup process. (24136)
Some backup jobs reseeded after the change from Daylight Savings Time to Standard Time. (26156)
4.1.2	Fixes in Version 6.20
When restoring QUSRSYS to another library, the restore completes successfully, but no *OUTQs are restored. (20071)
16 GB iSeries task with 100 MB deltas and 10 online safesets consumes 120+ GB of storage on the Vault. (19350)
IBMi 6.x:  Cannot restore individual member files from multi-membered files. (18932)
IFS backup performance is slow on IBM i Agent version 6.10. (18544)
File level (non-library objects) exclusions are scanned by the IBMi agent and errors for those exclusions are written to the backup log. (17549)
4.2	Known Issues
Schedule entries created using the Auto Job Creation Tool may have blank entries in "Work with Schedule" field for "Retention Name". (17579)
Jobs scheduled from Auto Job Creation tool may have invalid entries for Quick File Scanning with the error "*    not valid for parameter QUICKSCAN". (17578)
If the Agent userspace does not exist, the Agent exits with abnormal termination (SIGABRT). (17017)
Trigger backup fails with "lock semaphore failed".
WORKAROUND: To clean up Agent semaphores (needed after backup crashed and if system IPL did not occur), run the following command: CALL BUAGENT/TRGEXTPGM PARM('C') (16931)
*Sys backup fails with "Save Configuration objects failed".
WORKAROUND: The user should do a WRKJOB SYSBK1 and look at the job log of the most recent job to determine the system errors. If there are no job logs available then the user may look at the errors by running the following command manually:
"SAVCFG DEV(*SAVF) SAVF(BUAGENT/SYSSTS1)"
Typically the reason the backup fails is due to communication devices or controllers. These should be deleted and recreated. (16753)
IFS delta backup changes the attribute change data/time on directories and files. Symlinks are not affected. The backup process will restore the last access timestamp to be what it was before the backup. The attribute change timestamp is affected/updated. (16385)
*SYS Restore - restore configuration object failed due to CPF377C".
WORKAROUND: If any errors occur during a system state restore, (like CPF377C) then the user should perform DSPJOBJOG on the console session where the restore was run then review and resolve any system generated messages. (16174)
Running CPROBJ (compress object) during backup may trigger errors. (16074)
Restore from *IBM Job may also restore the objects inside of user libraries. (15964)
In work with task screen, last modified time/date is off by what appears to be GMT offset. (15470)
On *IBM restore receive errors for QSSP  library that programs/modules not found. (15413)
CHGAUT command errors are not reported in the agent log. (15301)
A file name with an apostrophe (') single quote or double quote (") characters that are not matched in name, fails on CHGAUT. (15300)
IFS backup of long paths may fail with "Fatal error in processing job". (15234)
User libraries that begin with Q are backed up as IBM default libraries as the Agent uses IBM’s internal listing to obtain the list of ALLUSR and *IBM. (14406)
During an *ALLUSR restore, an OS message may not be displayed properly in the log "REST-W-4096 CPF3756 USRQ QTMFQ00021 not restored to QUSRSYS" as well as in some other cases. (13725)
During an *ALLUSR restore, the incorrect message is logged as "REST-E-7365 failed to restore CPD372E FILE QAMOPVR not restored to Q". The REST-E-7365 message should contain the file name and not repeat the prior REST-W-4096 message. (13724)
During an *ALLUSR restore, the error appearing as "DISK-E-4954 Error writing data, ThreadApi is no longer in open status." The issue is that the API is not closing correctly after processing a 0 size FILE object because the file was locked during backup and the following object does not restore correctly.
WORKAROUND: Restore the object by itself. It should then restore correctly. (13723)
On an IFS restore you may receive the error "Unable to set file UID and GID for file". This message can appear if the user profile that owned the object at the time of the backup does not exist when the restore is done. For example, during a DR test, the *SYS Job was not run prior to running any other Jobs or a user profile was deleted from the system and the restore is being done from an older safeset which had an object that was owned by this deleted user profile. 
WORKAROUND: The user needs to review the messages and change the object to the proper object owner to allow their applications to function. (13606)
Following re-registration, if there is a Job where synch fails, they will sit in wrkactjob and must be ended by the user. (13588)
If you have created a retention (with Job Creation Tool and after database creation) and then delete the retention, the deleted retention will still be displayed (option 3). (13537)
Job names exceeding 8 characters may appear truncated due to OS limits. The OS only allows for up to 10 character system Job names so longer Agent Job names will be truncated. The Agent uses a 2 character suffix, namely _B, @B, #B, _R, #R, @R to indicate the type of process so that leaves 8 characters for the system Job name. If there is already another Agent Job with the same 8 character abbreviation, then the 8th position will be substituted with a number and the number will be incrementally increased until a unique name is found. The process will continue for the 7th, 6th, etc... until a unique name is found. (13525)
IBM i backup log can indicate error "No files backed up" when files are backed up. Members of multimember PF files are considered as directories and not as files. "No files backed up" is shown while directory is copied. (13497)
Backup/Restore of hard links not working correctly. (13400)
Error message "CPI2417 Job message queue for 000512/AGENT/BACKUP#R has been wrapped." This may occur with Jobs containing over 100K objects (OBJ). 
WORKAROUND:  Set JOBMSGQFL of all of the JOBDs of the Agent to *PRTWRAP. (13274)
Objects may not be backed up if file name contains special characters. For e.g. "/filename" The system is allowing the creation of a library with special characters in the name when it is included inside double quotes but it cannot be backed up. (13037)
Restoration to an alternate location is not allowed on Library name with a period “.” e.g. JAY.RST (13036)
The addition of "_END_MBR_.MBR" to address another IBM i issue, skews BACKUP log summary totals. As _END_MBR_.MBR appears numerous times in the backup logs, the totals for "# of files" and "# of errors will be skewed. (12560)
"Retry period" value in Vault settings is ignored. The default value of 1 hour is retained. (12531) 
Setup
If re-installing, you must first delete the setup library. For example: Delete TESETUP first before restoring the savf from the ftp site.
Remove Agent / Uninstall
If any objects in the Agent library are in use when the remove command is run, then those objects will not be deleted. The user may delete objects afterwards when they are no longer in use.
An Uninstall should be done at the beginning of a new session. If you wish to uninstall the Agent, you should logoff and then logon again to perform the Remove Program. If a failure message is received, you may have to repeat the process. 
Authority
Current programs run with authority of *USER, thus the user should use a profile with minimum *ALLOBJ, and *SECADM authority to ensure all objects can be backed up. Otherwise, a user will only be able to back up objects that they have authority to. *SAVSYS is not enough authority, since database members are read programmatically, and not with save commands. For *SYS backup, *SAVSYS is necessary.
Database Files
IBM limits access to deleted record information, thus during restore, deleted records will not be restored. Some very old AS400 applications relied on relative record numbers for indexing therefore, you may need to check with your application provider to see if you need to be concerned with relative record numbers and deleted records. Note: IBM strongly discourages the use of relative records numbers in applications since it is a system controlled value and gets changed whenever a RGZPFM command (database defrag) is run.
WORKAROUND: If relative record numbers are sensitive in your application then use the API option to back up database files.
Naming Convention
For Vault, Jobs, and Retention names, you must follow the IBM convention of: 
•	Not starting with a number
•	You may use "A" to "Z" and "0" to "9"
•	Special characters of "_", and "$", are allowed.
•	Vault Name - maximum 15 characters
•	Job Name - maximum 30 characters
•	Retention Name - maximum 32 characters
End Subsystem
If you try to End the Agent Subsystem (ENDSBS) during a backup or shutdown of the IBM i, you will receive the following: Error during backup: "Unexpected condition with QaneSava API. Reason 0913".
WORKAROUND: If needed, use ENDJOBABN command to forcefully end any non-responding Agent jobs. Note: This can only be done 10 minutes after the job has entered ending status.
Reconnection Settings
We highly recommend using the default reconnection settings on the Agent as they are optimized for the Vault/Agent. Only change the settings with technical support's guidance. The default times are: 
•	Reconnect Delay = 30 sec. 
•	Retry Timeout = 3600 sec.
Object Restore Fails if Object Already Exist
Restore objects of *DTAQ, *MSGQ, *JOBQ, *USRQ, *JRN, *JRNRCV types will fail if the object already exists. The Agent will skip over these objects continue. The error message "Command exception occurred using QaneSava API" will show in the log file. If you wish to restore/replace these types of objects, you must first make sure they don't exist or have been deleted before restoring them from the vault.
Object of specific type Fails when Restoring to alternate library. Types include the following:
 *SQLPKG, *JRN
Member attribute and text are not restored when the target system's QMLTTHDACN system value has been set to 3. 
WORKAROUND: For a restore, switch the QMLTTHDACN to 2 and then reset it to 3 when the restore is complete.
IFS device, block, special character and socket files are typically created by the OS install or OS running programs. The Agent does not restore these objects and some errors will be listed in the log file when attempted to restore these files.
Communication / Pre-Installation Requirements
There is an IBM OS bug on the network interface where the 100 Mbit interface can degrade to 0.4 Mbps. 
WORKAROUND: Use the same settings as your Hub, Switch, or Router (typically *AUTO) on the DUPLEX parameter on the CHGLINETH command to solve the problem. (Note: IBM default is *HALF) Please perform a FTP transfer test to and from the IBM I to a local PC and ensure the network is running optimally. We also recommend the following values for optimal network performance.
On the Ethernet line desc (description) set these values:
 GENTSTFRM(*NO)
 LINKSPEED(100M) (Use maximum value for the interface)
 LINESPEED(100M) (Use maximum value for the interface)
 DUPLEX(*AUTO) 
 On TCP/IP interface: TOS(*MAXTHRPUT)
 On TCP/IP Route: TOS(*MAXTHRPUT)
If you have the Defer option enabled, and the backup does not complete in the allotted time, the system will stop the backup, and complete it during the next backup time. To be able to stop the backup, the operating system must “abnormally” stop the backup job (the backup API). This will create errors in the Backup.log, but they are normal in this case. The log will also have a message similar to: “BKUP-W-0363 backup window expired, intra-file defer.” All object related errors after this line may be safely ignored, since the object that was deferred will be backed up during the subsequent backup.
Restore Database Performance. When restoring a database, performance will be enhanced if the database does not already exist in the destination location as the replace operation is more time consuming.
Do not use IBM Advanced Scheduler for submitting Agent Jobs. The Agent uses the standard job scheduler, which requires multi-threading. IBM Advanced Scheduler uses RCLRSC command internally, which is not compatible with multi-threaded applications. (10844/5865)
Error CPF3876 file not saved because of dependency on data dictionary. Error message CPF3876 "The file cannot be saved or restored unless the data dictionary is also being saved or restored." 
WORKAROUND: Create a CL program with SAVOBJ command to back up the database file and the depending data dictionary in one step and output it so a SAVF. Then specify the CL in the pre-command and specify the SAVF in the include statement on the task.
To get best delta results, back up only one PF and one dictionary per SAVF. Dump multiple SAVF to a specific library and then back up that library with the Agent after the pre-command completes. (9221)
Install program errors when you upgrade an Agent using Agent profile. You can't use the Agent profile during an upgrade. You must logon with "QSECOFR" level user ID to upgrade the Agent. (9021)
Intermittently unable to access the "Work with Agent Licenses" screen when entering menu selection number(5).
Workaround: Log out and log back in to the system. (6956)
If a backup is scheduled very soon after a Daylight Savings Time adjustment event (e.g., 2:01 am on the change day), some files may be re-deltized. 
Workaround: Schedule the backup to start prior to the Daylight Savings Time change, or at least 2 hours after. (5934)
System state restore "hangs up" if the grace period has expired.Grace period indicated as expired causes the system state to hang up "putting system into restricted state". (4144)
5	PRODUCT SUPPORT
5.1	Technical Support
Technical support is available from your provider. 
5.2	Product Updates
Product updates are available from your provider.
5.3	Documentation
The following documentation is available for the Agent:
•	Agent for IBM i User Guide
•	Agent for IBM i release notes (this document)