Save to Application (QaneSava) API

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 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.

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 Back up your server topic.

Saved Object Authorities

See Appendix D in the iSeries Security Referencebook.

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.

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 the 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. Refer to the save commands in the Control Language (CL) information for detailed information about valid parameters. Refer to the 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 compression (DTACPR) and Data compaction (COMPACT) parameters must not be used. These parameters are 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 compression (DTACPR) and Data compaction (COMPACT) keys must not be used. These keys are 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:

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