Data set allocation exit

In the ISPF configuration table keyword file, this exit is set with keyword DATA_SET_ALLOCATION_PROGRAM_EXIT.

You can specify an installation-written exit routine to create, delete, allocate, and deallocate data sets instead of using those functions provided by PDF. However, allocations done by ISPF, the TSO ALLOCATE command, or TSO commands are not handled by the exit. If you use your own data set allocation exit routine, it must be a program. CLISTs are not allowed.

Exit parameters

PDF passes the SVC 99 parameter list/dynamic allocation request table as input to the exit routine. The information in the parameter list depends on the type of request being processed and is obtained from the user. Register 1 points to the parameter list.

PDF uses these parameters to communicate with the allocation exit:

SVC99 parmlist pointer: A pointer to the SVC99 parmlist/dynamic allocation request table.
User storage pointer: A pointer to a 120-byte area that can be used to add new or changed text units.
Path name pointer: A pointer to an area of storage containing the absolute path name of the z/OS® UNIX file to be allocated. Set to zero if this is not a request to allocation a z/OS UNIX file.
Path name length: A fullword binary integer that is the length of the z/OS UNIX file path name. Set to zero if this is not a request to allocation a z/OS UNIX file.

In addition to these parameters, PDF allocates enough space for a total of 30 text unit pointers in the text unit pointer list. The unused pointers can be used in conjunction with the 120-byte user data area for adding or changing text units.

If the request is to allocate a data set, the parameter list contains the information in Table 1.

Table 1. Parameter list during allocation
Key	#Parms	Length	Parameter	Description	Exit may modify these parameters
0001	1	8	DDNAME	ddname to allocate data set to	No
0002	1	44	DSNAME	Data set name to allocate	No
0004	1	1	STATUS	Data set status	Yes
0005	1	1	NDISP	Normal data set disposition	Yes
0006	1	1	CDISP	Conditional data set disposition	Yes
0010	1	6	VLSER	Volume serial	No
0015	1	8	UNIT	unit name	No
0050	1	8	PASSW	Password for protected data set if a password was specified	No
0057	1	8	RTORG	Return data set organization	No
005D	1	6	RTVOL	Return volume serial from allocation	No
8017	1	1023 (max)	PATHNAME	Path name of the z/OS UNIX file to allocate. Pathname is of the form: `/dev/fdnnn` where nnn is the file descriptor number. The real path name can be obtained via the path name pointer and path name length parameters.	No
8018	1	4	PATHOPT	The file options for the z/OS UNIX file	No
801D	1	1	FILEORG	The organization of the z/OS UNIX file	No

If the request is to concatenate a data set, the parameter list contains the information in Table 2.

Table 2. Parameter list during concatenation
Key	#Parms	Length	Parameter	Description	Exit may modify these parameters
0001	1	8	DDNAMEx	List of ddnames corresponding to the data sets being concatenated	No
0004	0	0	PERMCC	Permanently concatenated attribute	No

If the request is to create a data set, the parameter list contains the information in Table 3.

Table 3. Create data set allocation parameter list
Key	#Parms	Length	Parameter	Description	Modifiable?
0001	1	8	DDNAME	ddname to allocate data set to	No
0002	1	44	DSNAME	Data set name to allocate	No
0004	1	1	STATUS	Data set status	Yes
0005	1	1	NDISP	Normal data set disposition	Yes
0006	1	1	CDISP	Conditional data set disposition	Yes
>0007 0008 0009	>1 1 1	>0 0 3	>TRKS CYLS BLKS	Space allocated in tracks or Space allocated in cylinders, or Space allocated in blocks	>Yes Yes Yes
000A	1	3	PSPACE	Primary space quantity	Yes
000B	1	3	SSPACE	Secondary space quantity	Yes
000C	1	3	DBLKS	Number of directory blocks	Yes
0010	1	6	VOLSER	Volume serial	Yes
0015	1	8	UNIT	Unit group (esoteric) name Device type Specific unit address	Yes
0020	1	1	PASPR	Data set is password protected: X'10' Data set cannot be read, changed, extended, or deleted. X'30' Data set can be read, but not changed, extended, or deleted.	Yes
>0022 006D 0023	>1 1 1	>5 7 2	>EXPDT EXPDTL RETPD	Expiration date - YYDDD or Expiration date - YYYYDDD or Retention period	>Yes Yes Yes
0030	1	2	BLKSZ	Block size	Yes
003C	1	2	DSORG	Data set organization	Yes
0042	1	2	LRECL	Logical record length	Yes
0049	1	1	RECFM	Record format	Yes
0050	1	8	PASSWORD	Data set password if specified	Yes
0052	0	0	PERM	Permanently allocated attribute	No
0057	1	2	RTORG	Return data set organization	No
005D	1	6	RTVOL	Return volume serial from allocation	No
8004	1	8	STORCLAS	Storage class used to allocate the data set	Yes
8005	1	8	MGMTCLAS	Management class used to allocate the data set	Yes
8006	1	8	DATACLAS	Data class used to allocate the data set	Yes
8010	1	1	AVGREC	Unit of allocation in terms of average record size: X'80' Bytes X'40' Kilobytes X'20' Megabytes	Yes
8012	1	1	DSNTYPE	Data set name type used to allocate the data set: X'80' Library X'40' PDS X'10' HFS X'08' Extreq X'04' Extpref X'02' Basic X'01' Large	Yes

If the request is to deallocate a data set, the parameter list contains the information in Table 4.

Table 4. Parameter list during deallocation
Key	#Parms	Length	Parameter	Description	Exit may modify these parameters
0001	1	8	DDNAME	ddname to free	No
0007	0	0	UNALC	Unallocate option	No

If the request is to delete a data set, the parameter list contains the information in Table 5.

Table 5. Parameter list during deletion
Key	#Parms	Length	Parameter	Description	Exit may modify these parameters
0002	1	44	DSNAME	DSNAME to free	No
0007	0	0	UNALL	Unallocate option	No

If the request is to delete a data set, it is done through the MVS™ SCRATCH macro. This allows unexpired data sets to be deleted.

Return codes

0: No errors; the exit has issued the SVC 99.
4: No errors; PDF issues the SVC 99.
8: Error occurred; the exit has formatted a message.
20: Severe error from the exit. The exit formats a message and PDF displays it in an error box.

If the allocation exit issues the SVC 99 and requests PDF to evaluate the error, the exit should return the SVC 99 return code to PDF in register 15 with the high-order bit of the register turned on.

If PDF issued the SVC 99, it places (by way of a VPUT) these variables into the shared pool in character format:

Z99RC: Return code from SVC 99
Z99ERROR: SVC 99 error code
Z99INFO: SVC 99 information code.