Qp0lSaveStgFree()--Save Storage Free

 #include <Qp0lstdi.h>

 int Qp0lSaveStgFree(
   Qlg_Path_Name_T          *Path_Name,
   Qp0l_StgFree_Function_t  *UserFunction_ptr,  
   void                     *Function_CtlBlk_ptr);

The Qp0lSaveStgFree() function calls a user-supplied exit program to save a stream file object (object type *STMF) and, upon successful completion of the exit program, frees the storage for the object and marks the object as storage freed. The *STMF object and its attributes remain on the system, but the storage occupied by the *STMF object's data is deleted. The *STMF object cannot be used until it is restored to the system. This is accomplished by either of the following:

• Restoring the object using the RST command.
• Requesting an operation on the object, requiring one of the following, which will dynamically retrieve (restore) the *STMF object:
  • Accessing the object's data (open(), creat(), MOV, CPY, CPYFRMSTMF, or CPYTOSTMF).
  • Adding a new name to the object (RNM, ADDLNK, link(), rename(), Qp0lRenameKeep(), or Qp0lRenameUnlink()).
  • Checking out the object (CHKOUT).

The restore operation is done by calling a user-provided exit program registered against the Storage Extension exit point QIBM_QTA_STOR_EX400. For information on this exit point, see Storage Extension Exit Program.

Qp0lSaveStgFree() returns EOFFLINE for an object that is already storage freed or returns EBUSY for an object that is checked out.

The user exit program can be either a procedure or a program.

Parameters

Path_Name

(Input) A pointer to a path name whose last component is the object that is saved and whose storage is freed. This path name is in the Qlg_Path_Name_T format. For more information on this structure, see Path name format.

If the last component of the path name supplied on the call to Qp0lSaveStgFree() is a symbolic link, then Qp0lSaveStgFree() resolves and follows the link to its target and performs its normal Qp0lSaveStgFree() functions on that target. If the symbolic link refers to an object in a remote file system, Qp0lSaveStgFree() returns ENOTSUP to the calling program.

UserFunction_ptr

(Input) A pointer to a structure that contains information about the user exit program that the caller wants Qp0lSaveStgFree() to call to save an *STMF object. This user exit program can be either a procedure or a program. If this pointer is NULL, Qp0lSaveStgFree() does not call an exit program to save the object but does free the object's storage and marks it as storage freed.

User Function Pointer
Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Function type flag
14	E	CHAR(10)	Program library
4	4	CHAR(10)	Program name
24	18	CHAR(1)	Multithreaded job action
25	19	CHAR(7)	Reserved
32	20	PP(*)	Procedure pointer to exit procedure

Function type flag. A flag that indicates whether the Save Storage Free exit program called by Qp0lSaveStgFree() is a procedure or a program. If the exit program is a procedure, this flag is set to 0, and the procedure pointer to exit procedure field points to the procedure called by Qp0lSaveStgFree(). If the exit program is a program, this flag is set to 1 and a program name and program library are provided, respectively, in the program name and program library fields. Valid values follow:

0	QP0L_USER_FUNCTION_PTR: A user procedure is called.
1	QP0L_USER_FUNCTION_PGM: A user program is called.

Multithreaded job action. (Input) A CHAR(1) value that indicates the action to take in a multithreaded job. The default value is QP0L_MLTTHDACN_SYSVAL. For release compatibility and for processing this parameter against the QMLTTHDACN system value, x'00, x'01', x'02', & x'03' are treated as x'F0', x'F1', x'F2', and x'F3'.

x'00'	QP0L_MLTTHDACN_SYSVAL: The API evaluates the QMLTTHDACN system value to determine the action to take in a multithreaded job. Valid QMLTTHDACN system values follow: '1' Call the exit program. Do not send an informational message. '2' Call the exit program and send informational message CPI3C80. '3' The exit program is not called when the API determines that it is running in a multithreaded job. ENOTSAFE is returned.
x'01'	QP0L_MLTTHDACN_NOMSG: Call the exit program. Do not send an informational message.
x'02'	QP0L_MLTTHDACN_MSG: Call the exit program and send informational message CPI3C80.
x'03'	QP0L_MLTTHDACN_NO: The exit program is not called when the API determines that it is running in a multithreaded job. ENOTSAFE is returned.

Procedure pointer to exit procedure. If the function type flag is 0, which indicates that a procedure is called instead of a program, this field contains a procedure pointer to the procedure that Qp0lSaveStgFree() calls. This field must be NULL if the function type flag is 1.

Program library. If the function type flag is 1, indicating a program is called, this field contains the library in which the program being called (identified by the program name field) is located. This field must be blank if the function type flag is 0.

Program name. If the function type flag is 1, indicating a program is called, this field contains the name of the program that is called. The program should be located in the library identified by the program library field. This field must be blank if the function type flag is 0.

Reserved. A reserved field. This field must be set to binary zero.

Function_CtlBlk_ptr

(Input) A pointer to any data that the caller of Qp0lSaveStgFree() wants to have passed to the user-defined Save Storage Free exit program that Qp0lSaveStgFree() calls to save an *STMF object. Qp0lSaveStgFree() does not process the data that is referred to by this pointer. The API passes this pointer as a parameter to the user-defined Save Storage Free exit program that was specified on its call. This is a means for the caller of Qp0lSaveStgFree() to pass information to and from the Save Storage Free exit program.

Authorities

The following table shows the authorization required for the Qp0lSaveStgFree() API.

Return Value

Error Conditions

If Qp0lSaveStgFree() is not successful, errno indicates one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when both of the following conditions occur:
   
   
   • Where multiple threads exist in the job.
     
     
   • The object this function is operating on resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. If the Save Storage Free exit program calls the SAV command or the QsrSave function or any other function that is not threadsafe, and there are secondary threads active in the job, Qp0lSaveStgFree() may fail as a result.
   
   
3. If the Save Storage Free exit program is not threadsafe or uses a function that is not threadsafe, then Qp0lSaveStgFree() is not threadsafe.
   
   
4. This function will fail with error code [EINVAL] if the stream file this function is operating on is a virtual volume.

Related Information

• The <Qp0lstdi.h> file
• QlgSaveStgFree()--Save Storage Free (using NLS-enabled path name)
• Save Storage Free Exit Program

Example

See Qp0lGetAttr() description for a code example that shows a call to Qp0lSaveStgFree() by using a procedure as the exit program. This API also shows an example of a call to Qp0lGetAttr().

[ Back to top | Backup and Recovery APIs | UNIX-Type APIs | APIs by category ]