Spooled File Security Exit Program
Required Parameter Group:
| 1 | Return code | Output | Char(1) |
| 2 | Format name | Input | Char(8) |
| 3 | Spooled file information | Input | Char(*) |
QSYSINC Member Name: espsecrg
Exit Point Name: QIBM_QSP_SECURITY
Exit Point Format Name: SPSY0100, SPSY0200
Exit Point QIBM_QSP_SECURITY allows registered exit programs to control access to spooled files on a file-by-file basis. The exit programs will be called at the beginning of each IBM i spool command or API, except under any of the following conditions:
- The job or thread has spool control (*SPLCTL) special authority. The special authority may originate from the user profile, group profile, or adopted authority.
- The job or thread has job control (*JOBCTL) special authority and the spooled file resides on an output queue with OPRCTL(*YES). The special authority may originate from the user profile, group profile, or adopted authority.
- The command or API is executed in a system job (including SCPF), a subsystem monitor job, or any job that is running under one of the following system user profiles:
QAUTPROF, QCLUMGT, QCOLSRV, QDBSHR, QDBSHRDO, QDFTOWN, QDIRSRV, QDLFM, QDOC, QDSNX, QFNC, QGATE, QLPAUTO, QLPINSTALL, QMSF, QNETSPLF, QNFSANON, QNTP, QPEX, QPM400, QRJE, QSNADS, QSPL, QSPLJOB, QSRVAGT, QSYS, QTCP, QTFTP, QTSTRQS.
Up to ten programs may be registered for each format for this exit point.
Authorities and Locks
A user must have all object (*ALLOBJ) and security administrator (*SECADM) special authorities to add an exit program to the QIBM_QSP_SECURITY exit point using the registration facilities, or to remove an exit program from the exit point.
Users of the exit point are not required to have any authority to the exit programs or exit program libraries.
Required Parameter Group
- Return code
- OUTPUT; CHAR(1)
The value returned to the exit point to indicate whether the user is allowed to perform the spool function. The return code will be initialized to blank (0x40) by the operating system before each exit program is called. The possible returned values are:
0 The function is not allowed by the registered exit program. 1 The function is allowed by the registered exit program. Any other return code value indicates that the exit program does not care whether the function is performed or not.
- Format name
- INPUT; CHAR(8)
The name of the format used to call the registered exit program. The valid format names are:
- SPSY0100
- The exit programs registered with this format are called for every spooled file, including those created and owned by the current job.
- SPSY0200
- The registered exit programs are only called for spooled files that are not owned by the current job.
- Spooled file information
- INPUT; CHAR(*)
The spooled file information structure identifies the function (command or API) and the spooled file about to be acted upon. If the spooled file is being moved via the CHGSPLFA command or QSPMOVSP API, it also contains the name of the new output queue and its library. If the spooled file is not being moved, the new output queue and new output queue library fields will be blank.
SPSY0100 and SPSY0200 Format
The following table shows the layout of the Spooled file information parameter. The same data structure is used for both SPSY0100 and SPSY0200 exit programs. For detailed descriptions of the fields in this table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of spooled file information |
| 4 | 04 | CHAR(10) | Function Identifier |
| 14 | 0E | CHAR(10) | Current user profile name |
| 24 | 18 | CHAR(10) | Job name |
| 34 | 22 | CHAR(10) | Job user name |
| 44 | 2C | CHAR(6) | Job number |
| 50 | 32 | CHAR(10) | Spooled file name |
| 60 | 3C | BINARY(4) | Spooled file number |
| 64 | 40 | CHAR(8) | Job system name |
| 72 | 48 | CHAR(7) | Date file opened (created) |
| 79 | 4F | CHAR(6) | Time file opened (created) |
| 85 | 55 | CHAR(1) | Reserved |
| 86 | 56 | CHAR(10) | Output queue name |
| 96 | 60 | CHAR(10) | Output queue library name |
| 106 | 6A | CHAR(10) | Auxiliary storage pool device name |
| 116 | 74 | BINARY(4) | Auxiliary storage pool |
| 120 | 78 | CHAR(10) | Form type |
| 130 | 82 | CHAR(10) | New output queue name |
| 140 | 8C | CHAR(10) | New output queue library name |
| 150 | 96 | CHAR(10) | New auxiliary storage pool device name |
| 160 | A0 | BINARY(4) | New auxiliary storage pool |
| 164 | A4 | CHAR(10) | User-specified data |
| 174 | AE | CHAR(255) | User-defined data |
Field Descriptions
Auxiliary storage pool. The number of the auxiliary storage pool (ASP) that the spooled file's output queue library is stored on. The possible values are:
| 0 | Value is not defined. See Usage Note 5. |
| 1 | System ASP |
| 2-255 | One of the ASPs. |
Auxiliary storage pool device name. The name of the auxiliary storage pool (ASP) device that the spooled file's output queue library is stored on. The possible values are:
| *SYSBAS | The output queue resides on the system ASP (ASP 1) or one of the defined basic user ASPs (ASPs 2-32) |
| Device name | The name of the ASP device that the output queue resides on. |
| Blank | The name of the ASP device could not be retrieved. See Usage Note 5. |
Current user profile name. The name of the user profile that is currently active in the job or thread.
Date file opened (created). The date the file was opened, in CYYMMDD format, where:
| C | Century, where 0 indicates years 19xx and 1 indicated years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
Form type. The type of form to be loaded in the printer to print this file.
Function identifier. The name of the command or application program interface (API) currently being executed. The possible values are:
| CHGSPLFA | Change Spooled File Attributes |
| CPYSPLF | Copy Spooled File |
| DLTSPLF | Delete Spooled File |
| DSPSPLF | Display Spooled File |
| EXPORT | Program interface used by iSeries Navigator to export an EBCDIC spooled file to an ASCII desktop |
| HLDSPLF | Hold Spooled File |
| QGSLRSC | List Spooled File AFPDS Resources API |
| QSPMOVSP | Move Spooled File API |
| QSPOPNSP | Open Spooled File API |
| QUSRSPLA | Retrieve Spooled File Attributes API |
| RLSSPLF | Release Spooled File |
| RST | Restore Object, Restore Library, or QSRRSTO API |
| SAV | Save Object, Save Library, or QSRSAVO API |
| SNDNETSPLF | Send Network Spooled File |
| SNDTCPSPLF | Send TCP/IP Spooled File |
| WRKPRTSTS | Work with Printing Status |
| WRKSPLFA | Work with Spooled File Attributes |
Job name. The name of the job that owns the spooled file.
Job number. The number of the job that owns the spooled file.
Job user name. The name of the user profile that owns the spooled file.
Length of spooled file information. The length of the Spooled file information structure.
New auxiliary storage pool. The number of the auxiliary storage pool (ASP) of the new output queue's library if the spooled file is being moved or restored. The possible values are:
| 0 | This field is not being used. |
| 1 | System ASP |
| 2-255 | One of the ASPs. |
New auxiliary storage pool device name. The name of the auxiliary storage pool (ASP) of the new output queue's library if the spooled file is being moved or restored. The possible values are:
| *SYSBAS | The output queue resides on the system ASP (ASP 1) or one of the defined basic user ASPs (ASPs 2-32) |
| Device name | The name of the ASP device that the output queue resides on. |
| Blank | This field is not being used. |
New output queue library name. The name of the library that contains the output queue to which the spooled file is about to be moved or restored. If this field is not used, it will be blank.
New output queue name. The name of the output queue to which the spooled file is about to be moved. If this field is not used, it will be blank.
Output queue library name. The name of the library that contains the output queue where the spooled file currently resides.
Output queue name. The name of the output queue where the spooled file currently resides.
Reserved. This field is reserved.
Spooled file name. The name of the spooled file.
Spooled file number. The number of the spooled file.
Time file opened (created). The time the file was opened, in HHMMSS format, where:
| HH | Hour |
| MM | Minutes |
| SS | Seconds |
User-defined data. Data defined by the user to be used by user applications of user-specified programs that process spooled files. The following values are supported:
| *NONE | No user-defined data is specified, |
| User-defined data | Data defined by the user. |
User-specified data. The ten characters of user-specified data that describe the file.
Usage Notes
For better run-time performance, each job retrieves a list of the QIBM_QSP_SECURITY registered exit programs at the first spool command or API, and this list is used for the life of the job. If a new program is registered for the exit point, any jobs already running on the system will ignore the new exit program. If an exit program is deregistered, any jobs already running will continue to call the program unless it is deleted or moved to another library. If a registered exit program is replaced, all jobs (including those that are already running on the system) will call the new program.
If multiple exit programs are registered, the SPSY0100 programs are called first, then the SPSY0200 programs. If any program returns '0' (the "not allowed" value), control is immediately passed back to the spool function to issue its error message. Any remaining exit programs in the list for either format will not be called.
A few operating system functions create temporary spooled files, extract their data or display them, and then delete the files when they are finished. This is also a common practice with customer-written and third-party applications. Until now, it has always been assumed that users had complete authority to spooled files that they own. If you use format SPSY0100 you must be careful not to break these functions. For example, an exit program could use RTVJOBA or QUSRJOBI to retrieve its qualified job name, and if this matches the Job name, Job user name, and Job number in the Spooled File Information, and if the spooled file name is "QPDSPFD" or "QPDSPFFD", always return '1' or blank. Most of these issues can be avoided by using format SPSY0200 instead of SPSY0100.
If an exit program calls the same API or command that it was called to validate, a recursion error is likely to occur. For example, an exit program should not call the QUSRSPLA API when it was called with a Function identifier of QUSRSPLA — unless the exit program adopts authority from a user profile with *SPLCTL special authority (such as QSECOFR) to prevent the exit program from being called again.
When the Function identifier is "RST", the spooled file to be restored does not actually exist yet when at the point where the exit programs are called. Therefore any spool functions issued by an exit program against the file (such as calling the QUSRSPLA API to retrieve additional attributes) will fail with a File Not Found or Job Not Found error. Also, the Auxilliary Storage Pool information for the output queue library where the spooled file currently resides is undefined.
When the Function identifier is "SAV" or "RST", a return value of '1' is ignored; the user must still have *SAVSYS special authority or have sufficient authority to the output queue in order to save or restore the file. A return value of '0' will prevent the spooled file from being saved or restored.
If the QSRSAVO or QSRRSTO API is used to save or restore spooled files, and if the user attempts to change a spooled file expiration date using the API list functions, the exit programs will be called again with a Function identifier of "CHGSPLFA". If an exit program returns '0' for this CHGSPLFA call, the spooled file will be saved or restored but its expiration date will not be changed.
Exit program introduced: IBM® i 7.1
[ Back to top | Print APIs | APIs by category ]