COZZI-Save Lib to Rolling SAVF (SAVROLLING)

Where allowed to run: All environments (*ALL)
Threadsafe: No
Parameters
Examples
Error messages

The COZZI-Save Lib to Rolling SAVF (SAVROLLING) command saves a library to a save file using an incremental naming convention. Use this command to save "generations" of a library over time.

For example, every week you could save a library named CUSTDATA to a save file and place the save file in library MYBACKUP. Using this command, each time the CUSTDATA library is saved, a save file is created with a numeric suffix. For example, CUSTDATA, CUSTDATA1, CUSTDATA2... If MAXGEN(4) is specified, then save files with the following names could exist: CUSTDATA, CUSTDATA1, CUSTDATA2, CUSTDATA3. The SAVF without a suffix is the most rescent save. The next time the SAVROLLING command is run over the CUSTDATA library, the existing save files are bumped down, and the oldest save file is deleted. Save file CUSTDATA2 becomes CUSTDATA3, CUSTDATA1 becomes CUSTDATA3 and a fresh CUSTDATA SAVF is created, containing the most recent save image. The command is limited to 1, 10 or 100 generations (images). SAVROLLING can create a maximum number of save file images based on the library's name, as follows:

Library
Name     Max Backup
Length   Generations
  10         1
   9        10
 <=8       100

If the maximum generations specified on the MAXGEN parameter exceeds the above limit, the max is used instead of the user-specified value.

Restrictions:

Top

Parameters

Keyword Description Choices Notes
LIB Library(s) to save Values (up to 300 repetitions): Name Required, Positional 1
SAVFLIB Library for save file(s) Name Required, Positional 2
CRTLIB Create SAVFLIB Library *YES, *NO Optional, Positional 3
TGTRLS Target Release for save Character value, *CURRENT, *PRV Optional, Positional 4
MAXGEN Maximum generations to keep Integer, 3 Optional, Positional 5
TEXT Save file text (description) Character value, *DFT, *BLANK Optional, Positional 6
SAVACT Save while active *NO, *YES, *LIB, *SYNCLIB, *SYSDFN Optional, Positional 7
SAVACTWAIT Save active wait time Element list Optional, Positional 8
Element 1: Object locks 0-99999, 120, *NOMAX
Element 2: Pending record changes 0-99999, *LOCKWAIT, *NOCMTBDY, *NOMAX
Element 3: Other pending changes 0-99999, *LOCKWAIT, *NOMAX
SAVACTMSGQ Save while active msg queue Qualified object name Optional, Positional 9
Qualifier 1: Save while active msg queue Name, *NONE, *WRKSTN
Qualifier 2: Library Name, *LIBL, *CURLIB
Top

Library(s) to save (LIB)

Specifies the library name(s) to be saved. Up to 300 library names at a time may be saved to individual save files.

This is a required parameter.

You can specify 300 values for this parameter.

name
Specify the name of library to save.
Top

Library for save file(s) (SAVFLIB)

Specifies the library into which the SAVF (save files) are created.

This is a required parameter.

name
Specify the name of library that is used to store the save files that are created by the command.
Top

Create SAVFLIB Library (CRTLIB)

Specifies whether to create the SAVFLIB if it does not exist.

*YES
If the save file library does not exist, it is created.
*NO
If the save file library does not exist, the command ends. If it already exists, the save continues.
Top

Target Release for save (TGTRLS)

Specifies specify the target release for the SAVLIB operation.

*CURRENT
The current release of IBM i is used as the target release for the SAVLIB.
*PRV
The previous release level of IBM i is used as teh target release for the SAVLIB.
character-value
Specify the a specify release level in VxRyMz format, for the SAVLIB.
Top

Maximum generations to keep (MAXGEN)

Specifies the maximum number of generations to be retained. Once the maximum generations is reached, the highest numbered SAVF (save file) is deleted before the newest SAVLIB is performed. This is done so that the rolling effect of the save file names/generations can be accomplished prior to the save--allowing the most current version to always be named with generation sequence number 1.

3
The default is 3 generations. When a 4th generation is created, generation 3 is deleted and generations 1 and 2 are rolled up to (i.e., renamed) to generations 2 and 3 and then the new generation 1 is created.
integer
Specify the maximum number of generations to retain. NOTE: This is further restricted by the length of the library name being saved. A name-suffix is used when creating the save files, limiting the generations. This also means that library names that are 10 characters in length CANNOT be saved by the SAVROLLING command.
Top

Save file text (description) (TEXT)

Specifies the text description for the save file being created.

*DFT
The text description is set to: "Saved on yyyyMMMdd HH:MM:SS" where dd is the day of the month, MMM is the name of the month (in words) and yyyy is the 4-digit year, and HH:MM:SS is the time of the save operation. For example, if the save is performed at 7:00 PM on Feb 15 2012 the text description becomes: "Saved on 2012FEB15 19:00:00".
*BLANK
No text is added to the save file description, however, the date/time stamp is still inserted to the right-end of the text description.
character-value
Specify the text description for the save file.
Top

Save While Active (SAVACT)

Specifies whether an object can be updated while it is being saved.

Note: If your system is in a restricted state and the SAVACT parameter is specified, the save operation is performed as if SAVACT(*NO) was specified.

*NO
Objects that are in use are not saved. Objects cannot be updated while being saved.
*YES or *LIB
Objects in a library can be saved while they are in use by another job. All of the objects in a library reach a checkpoint together and are saved in a consistent state in relationship to each other.
*SYNCLIB
Objects in a library can be saved while they are in use by another job. All of the objects and all of the libraries in the save operation reach a checkpoint together and are saved in a consistent state in relationship to each other.

Note: If you specify this value and you are saving many libraries, it can take a long time to reach a checkpoint for all of the objects and libraries in the save operation.

*SYSDFN
Objects in a library can be saved while they are in use by another job. Objects in a library may reach checkpoints at different times and may not be in a consistent state in relationship to each other.
Top

Save active wait time (SAVACTWAIT)

Specifies the amount of time to wait for an object that is in use, or for transactions with pending changes to reach a commit boundary, before continuing the save operation.

Element 1: Object locks

For each object that is in use, specifies the amount of time to wait for the object to become available. If an object remains in use for the specified time, the object is not saved.

120
The system waits up to 120 seconds for each individual object lock before continuing the save operation.ded by the default parameter value.
*NOMAX
No maximum wait time exists.
0-99999
Specify the number of seconds to wait for each individual object lock before continuing the save operation. ed by the range-limited parameter value.

Element 2: Pending record changes

For each group of objects that are checkpointed together, specifies the amount of time to wait for transactions with pending record changes to reach a commit boundary. The Save active (SAVACT) parameter determines which objects are checkpointed together. If 0 is specified, all objects being saved must be at commit boundaries. If any other value is specified, all objects that are journaled to the same journals as the objects being saved must reach commit boundaries. If a commit boundary is not reached in the specified time, the save operation is ended, unless the value *NOCMTBDY is specified.

*LOCKWAIT
The system waits up to the value specified for Element 1 for transactions with pending record changes to reach a commit boundary.
*NOCMTBDY
The system will save objects without requiring transactions with pending record changes to reach a commit boundary. Therefore, objects may be saved with partial transactions.

If you restore an object that was saved with partial transactions, you cannot use the object until you apply or remove journal changes (APYJRNCHG or RMVJRNCHG command) to reach commit boundaries. You will need all journal receivers that contain information about the partial transactions to apply or remove the changes. Until you apply or remove the changes, any future save of that object will include the partial transactions, even if you do not specify *NOCMTBDY.

*NOMAX
No maximum wait time exists.
0-99999
Specify the number of seconds to wait for each individual object lock before continuing the save operation.

Element 3: Pending record changes

For each library, specifies the amount of time to wait for transactions with other pending changes to reach a commit boundary. Other pending changes include the following:

If a commit boundary is not reached for a library in the specified time, the library is not saved.

*LOCKWAIT
The system waits up to the value specified for Element 1 for transactions with pending record changes to reach a commit boundary.
*NOMAX
No maximum wait time exists.
0-99999
Specify the number of seconds to wait for the types of transactions that are listed above to reach a commit boundary.
Top

Save active message queue (SAVACTMSGQ)

Specifies the message queue that the save operation uses to notify the user that the checkpoint processing for a library is complete. Specify QSYSOPR to have the messages routined to the System Operator (QSYSOPR) message queue. A separate message is sent for each library to be saved when the *SYSDFN or *LIB value is specified for the Save active (SAVACT) parameter. When *SYNCLIB is specified for the SAVACT parameter, one message is sent for all libraries in the save operation.

This parameter can be used to save the objects at a known, consistent boundary to avoid additional recovery procedures following a restore operation. Applications can be stopped until the checkpoint processing complete message is received.

Single Values

*NONE
No notification message is sent.
*WRKSTN
The notification message is sent to the work station message queue. This value is not valid in batch mode.
name
Specify the name of the message queue to be used. Specify QSYSOPR if the System Operator message queue should be used.

Qualifier 2: Library

*LIBL
The library list for the current thread is searched for the message queue name.
*CURLIB
The current library for the job is used to locate the message queue. If no library is specified as the current library for the job, the QGPL library is used.
name
Specify the name of the library where the message queue is located.
Top

Examples for SAVROLLING

Example 1: Simple Command Example

SAVROLLING  LIB(CUSTDATA MYLIB) SAVFLIB(QGPL) MAXGEN(4)

This command saves library CUSTDATA and then MYLIB to save files named CUSTDATA1 and MYLIB1 in the QGPL library.

Top

Error messages

Unknown
Top