Save to Application (QaneSava) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | User space format name | Input | Char(8) |
| 3 | Status format name | Input | Char(8) |
| 4 | Status information | Output | Char(*) |
| 5 | Length of status information | Input | Binary(4) |
| 6 | Error code | I/O | Char(*) |
Service Program Name: QANESERV
Default Public Authority: *USE
Threadsafe: No
The Save to Application (QaneSava) API enables an application to receive the save records that are generated by a save-to-save-file operation. The application defines the save operation by specifying the type of save command, and by providing the save command parameters. The API calls an exit program to transfer the save records to the application instead of to the save file.
To use the API, the application must provide the following:
- A user space that contains the required input parameter group
- An exit program
When processing the save command, the API does the following:
- Calls the exit program to indicate the start of the transfer sequence
- Submits the save command for processing
- Calls the exit program repeatedly to transfer the save records
- Calls the exit program to signal the end of the save operation
- May call the exit program to force an abnormal end to the save operation
The program that calls the API is suspended while the save operation is being processed.
Restrictions
QTEMP should not be specified for the library name on the OUTFILE or SAVACTMSGQ parameter because the save command is submitted by a prestart job running in the QSYSWRK subsystem and not in the job that called the API. Locks should not be applied to save objects that would conflict with locks applied by the save operation running in the prestart job.
Objects saved by this API can only be restored by using the Restore from Application (QaneRsta) API, and only if restored to a current or a later release of the operating system from which these were saved.
The application must store the save records in the order presented, without modification, for the objects to be successfully restored.
Because the save command is processed from within a prestart job the adopted authority of the thread using the Save to Application (QaneSava) API will not be available to the save command. One way to give the prestart job more authority is to use the adopted authority to swap user profiles within the application before calling the Save to Application (QaneSava) API.
Authorities and Locks
- Exit Program Library Authority
- *EXECUTE
- Exit Program Authority
- *EXECUTE
- User Space Lock
- *SHRNUP
- User Space Library Authority
- *USE
- User Space Authority
- *USE
- Save Command Library Authority
- *EXECUTE
- Save Command Authorities
- See the save command
- Saved Object Locks
- See the Backing up your system topic collection.
- Saved Object Authorities
- See Authority required for objects used by commands in the Security reference topic collection.
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that contains all the control information for the save operation. The first 10 characters contain the user space name. The second 10 characters contain the name of the library where the user space is located.
You can use the following special values for the library name:
*CURLIB The job's current library is used to locate the user space. If no library is specified as the current library for the job, the QGPL library is used. *LIBL The library list is used to locate the user space. The actual library that is used is returned in the status information.
- User space format name
- INPUT; CHAR(8)
The format name for the input parameters that are contained in the user space. For the format of the structure, see SVRS0100 Format.
- Status format name
- INPUT; CHAR(8)
The format name for the status information returned on the API call. For the format of the structure, see SRST0100 Format.
- Status information
- OUTPUT; CHAR(*)
The status information returned on the API call.
- Length of status information
- INPUT; BINARY(4)
The length of the status information returned on the API call. The minimum length is 8 bytes.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
SVRS0100 Format
This format defines the input parameter group for the API.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of structure |
| 4 | 4 | BINARY(4) | Offset to save command parameters |
| 8 | 8 | BINARY(4) | Length of save command parameters |
| 12 | C | BINARY(4) | Offset to application data |
| 16 | 10 | BINARY(4) | Length of application data |
| 20 | 14 | BINARY(4) | Save command type |
| 24 | 18 | CHAR(10) | Exit program name |
| 34 | 22 | CHAR(10) | Exit program library |
| 44 | 2C | CHAR(8) | Target release |
| CHAR(*) | Save command parameters | ||
| CHAR(*) | Application data | ||
Field Descriptions
Application data. Information that the application wants passed to the exit program. The content of this information is defined by the application. This field could contain information specific to the object being saved (such as the object name, size, and so forth), or it could contain the qualified name of another object that contains this information.
Exit program library. The name of the library that contains the exit program called by the API. the exit program.
Exit program name. The name of the exit program that is called by the API. See Save to Application Exit Program for additional details.
Length of application data. The length of the application data. This value is passed to the exit program. This value must be set to zero if there is no application data.
Length of save command parameters. The length of the save command parameters. The maximum allowable length is 32500 bytes for save commands.
Length of structure. The length of this structure, from the start of the input parameters to the last byte of the application data.
Offset to application data. The byte offset from the beginning of the user space to the start of the application data. This value must be set to zero if there is no application data.
Offset to save command parameters. The byte offset from the beginning of the user space to the start of the save command parameters.
Save command parameters. A character string that contains the save command parameters or save keys. These parameters are validated when the API submits the command for processing. See the save commands in the Control language topic collection for detailed information about valid parameters. See Save Object (QsrSave) API or Save Object List (QSRSAVO) API for detailed information about valid keys.
These additional restrictions apply to the save command parameters when you use this API:
- The parameters specified must be consistent with the save command type.
- The parameters must not include the save command name.
- The parameters must be separated by at least one blank character.
- Only a single library name can be used with the LIB parameter.
- The Clear (CLEAR) , Device (DEV), Save file (SAVF) and Target release (TGTRLS) parameters must not be used. These parameters are provided by the API.
- The Data compaction (COMPACT) parameter must not be used. This parameter is not supported by the API.
- The End of media option (ENDOPT), File expiration date (EXPDATE), Label (LABEL), Media definition (MEDDFN), Optical file (OPTFILE), Sequence number (SEQNBR), Starting library (STRLIB), Use optimum block (USEOPTBLK) and Volume identifier (VOL) parameters must not be used. These parameters are inconsistent with the save file operation provided by the API.
The following examples illustrate the save command parameters that are required for typical save scenarios:
- Example 1: Save command type 1 (SAV)
OBJ('/*') ('/QSYS.LIB' *OMIT) ('/QDLS.LIB' *OMIT)These parameters save all objects that are not in libraries and that are not document library objects.
- Example 2: Save command type 2 (SAVOBJ)
OBJ(FILE*) LIB(MYLIB) OBJTYPE(*FILE)
These parameters save all files with names that start with the characters FILE* in the library named MYLIB.
- Example 3: Save command type 4 (SAVLIB)
LIB(JOE)
These parameters save the library named JOE.
These additional restrictions apply to the command parameters when you use the Save Object (QsrSave) API or Save Object List (QSRSAVO) API.
- The keys specified must be consistent with save to save file operations.
- The Clear (CLEAR), Device (DEV), Save file (SAVF) and Target release (TGTRLS) keys must not be used. These keys are provided by this API.
- The Data compaction (COMPACT) key must not be used. This key is not supported by this API.
- The End of media option (ENDOPT), File expiration date (EXPDATE), Label (LABEL), Media definition (MEDDFN), Optical file (OPTFILE), Sequence number (SEQNBR), Starting library (STRLIB), Use optimum block (USEOPTBLK) and Volume identifier (VOL) keys must not be used. These keys are inconsistent with the save file operation provided by the API.
- The starting offset for the keys is always 0 and not the offset of the save command parameters.
- All offset and integer values within the keys must be aligned on 4-byte boundaries.
- All pointers within the keys must be aligned on 16-byte boundaries.
Save command type. The type of save command that is to be processed.
| 1 | Save (SAV) command |
| 2 | Save Object (SAVOBJ) command |
| 3 | Save Document Library Object (SAVDLO) command |
| 4 | Save Library (SAVLIB) command |
| 5 | Save Changed Object (SAVCHGOBJ) command |
| 6 | Save Object (QsrSave) API |
| 7 | Save Object List (QSRSAVO) API |
| 8 | Save System Information (SAVSYSINF) command |
Target release. The release level of the operating system on which you intend to use the object being saved. The value passed in this field is ignored when the value for Save command type is 8. The default is *CURRENT. The possible values are:
| blanks | The default value is used. |
| *CURRENT | The object is to be restored to, and used on, the release of the operating system that is currently running on your system. The object can also be restored to a system with any subsequent release of the operating system. |
| *PRV | The object is to be restored to the previous release with modification level 0 of the operating system. The object can also be restored to a system with any subsequent release of the operating system installed. |
| target-release | The release in the format VxRxMx. The object can
be restored to a system with the specified release or with any subsequent
release of the operating system.
Valid VxRxM0 values depend on the current version, release, and modification level, and depend on the save operation being performed. For a complete list of valid values for TGTRLS, see Current release-to-previous release support in the Recovering your system topic collection. |
SRST0100 Format
This format defines the status information that is returned on the API call.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Transfer time |
| 12 | C | BINARY(4) | Transfer block size |
| 16 | 10 | BINARY(4) | Transfer block multiplier |
| 20 | 14 | BINARY(4) | Last block size |
| 24 | 18 | CHAR(10) | User space library used |
| 34 | 22 | CHAR(2) | Reserved |
| 36 | 24 | BINARY(4) | Decimal transfer time |
Field Descriptions
Bytes returned. The number of status information bytes returned. If the value specified in the length of status information parameter is larger than the specified status information structure, this value is set to the last byte of the returned information.
Bytes available. The number of status information bytes available for the specified status information format.
Decimal transfer time.The decimal portion of the transfer time in millionths of a second. If the value returned for Transfer time was 5 and the value returned for Decimal transfer time was 827352, then the total transfer time was 5.827352 seconds.
Reserved.This field is unused and will be returned with blanks.
Transfer block size. The number of bytes in the blocks transferred by the exit program.
Transfer block multiplier. The number of blocks successfully transferred by the exit program.
Last block size. The number of bytes in the last block transferred by the exit program.
The true transfer size of the operation is equal to the transfer block size multiplied by the transfer block multiplier plus the last block size.
Transfer time. The elapsed time, in seconds, that begins when the application calls the API, and ends when the API returns to the caller.
User space library used. The name of the user space library that is used in the API call.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3700 E | All CPF37xx messages could be signalled. xx is from 01 to FF, excluding tape and diskette errors since the operation is a save to a save file. |
| CPF3800 E | All CPF38xx messages could be signalled. xx is from 01 to FF, excluding tape and diskette errors since the operation is a save to a save file. |
| CPF2115 E | Object &1 in &2 type *&3 damaged. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9800 E | All CPF98xx messages could be signaled. xx is from 01 to FF. |
| CPF9999 E | Function check. &1 unmonitored by &2 at statement &5, instruction &3. |
| CPFB8C0 E | Status information length for &1 API is not valid. |
| CPFB8C1 E | Unsupported value for &1 API. |
| CPFB8C2 E | Offset value for &1 API not valid. Reason &6. |
| CPFB8C3 E | Length value for &1 API not valid. Reason &6. |
| CPFB8C4 E | Unexpected condition with exit program for &1 API. Reason &6. |
| CPFB8C5 E | Parameter &2 specified more than once for API &1. |
| CPIB8C6 I | Trace data generated for API &1. |
| CPFB8C7 E | Unsupported value for &1 API. |
| CPFB8C8 E | Command syntax error detected by &1 API. |
| CPFB8C9 E | Command exception occurred using &1 API. |
| CPFB8CF E | Unexpected condition with &1 API. Reason &6. |
API introduced: V4R3
[ Back to top | Backup and Recovery APIs | APIs by category ]