AIFSPFGET

Returns spool file information.

Syntax



                 REC            I32A          @64A          RECA

AIFSPFGET (overall_status, itemnum_array, item_array, itemstatus_array,

                @64    REC     I32

             spf_addr, spf_id, user_id);

Parameters

overall_status

record by reference (required)

Returns the overall status of the call. A zero indicates a successful call. A negative value indicates an error in the overall call, not specific to any particular item. A positive value indicates the last element in itemstatus_array, signaling an error condition. Refer to appendix A for neanings of status values.

Record type: status_type (Refer to appendix B.)

itemnum_array

32-BIT digned integer array by reference (required)

An array of integers where each element is an item number indicating the information to be returned to a data structure pointed in the corresponding element in item_arrray. If n item numbers are being requested, element n+1 must be a zero to indiciate the end of the element list.

item_array

64-bit address array by reference (required)

An array where each element is a 64-bit address pointing to a data structure where information is returned. Information and its required data type are defined by the item number passed in the corresponding element in itemnum_array.

Array type: globalanyptr

itemstatus_array

record array by reference (required)

An array where each element returns the status of the operation performed in the corresponding element in item_array. A zero indicates a successful operation. A negative value indicates an error condition. A positive value indicates a warning. Refer to appendix A for meanings of status values.

Array type: status_type (Refer to appendix B.)

spf_addr

64-bit address by reference (required)

Array type: globalanyptr

itemstatus_array

record array by reference (required)

An array where each element returns the status of the operation performed in the corresponding element in item_array. A zero indicates a successful operation. A negative value indicates an error condition . A positive value indicates a warning. Refer to appendix A for meanings of status values.

Array type: status_type (Refer to appendix B.)

spf_addr

64-bit address by value (optional)

Passes the virtual address of the spool file for which information is desired.

Default: nil

spf_id

record by reference (required)

Passes the spool file ID of the spool file for which information is desired. If spf_addr also passed, spf_id is used for validation.

Record type: spf_id_type (Refer to appendix B.)

Default: nil

user_id

32-bit signed integer by value (optional)

The user ID assigned to a vendor at the time of purchase of the Architected Interface Facility: Operating System product. If it is not passed, the caller must have previously called AIFACCESSON.

Default:0

Operation Notes

AIFSPFGET accepts as an input key a spool file ID and/or a spool file address, which identifies the spool file that the information is to be returned on. The spool file address is the faster mechanism of the two. If both are provided, the address and the spool file ID are checked against each other to make sure that they match the same spool file. If they don't match, the spool file ID will be used as it is the unique key while the spool file address is reusable and not unique. The mismatch of the two keys indicates that the spool file entry pointed to by the address is no longer used by the file identified by the spool file ID. It is most likely that the spool file has been purged and the entry has been reused by a later created spool file. AIFSPFGET will then use the spool file ID to verify the existence of the spool file.

If the two keys match, the spool file address will be used. Note that the address is not a unique identifier. The address may be pointing to a deallocated entry where the information of a deleted spool file is still available. Therefore, it is possible for AIFSPFGET to successfully return information for a spool file that has been deleted but the spool file address and ID do not match.

AIFSPFGET Items

The following two tables provide summary and detailed descriptions of the item numbers associated with spool file information.

Item Summary

The following table summarizes the item numbers associated with spool file information. For more detailed information about these item numbers, refer to the tables of AIFSPFGET and AIFSPFPUT item descriptions.

Table 3-31 Spool File Information Item Summary

Item	Type	Description	Put	Ver	Min	Max	Error#
8501	I32	File state	Y	Y	0	10	-8043
8502	I32	Priority	Y	Y	0	14	-8047
8503	I32	Restartable?	N	Y
8504	I32	Disposition	Y	Y	1	2	-8048
8505	I32	Private?	N	Y
8506	I32	Forms message?	N	Y
8507	I32	Incomplete?	Y	Y	0	1	-8049
8508	I32	Job or data file?	N	Y
8509	I32	Aborted `$STDLIST`?	Y	Y	0	0	0
8510	I32	Spool file ID	N	Y
8511	I32	Copies requested	Y	Y	1	65535	-8050
8512	I32	Ready date	Y	Y
8513	I32	Ready time	Y	Y
8514	I32	Number of pages	Y	Y
8515	I32	Restart page	Y	Y
8516	CA32	Creator name/account	Y	Y
8517	I32	Job/session number	Y	Y
8518	CA16	Job name	Y	Y
8519	CA16	Spool file designator	Y	Y
8520	CA18	Target device	Y	Y
8521	I32	Device record size	N	Y
8522	BIT16	Device type	N	Y
8523	BIT16	Device subtype	N	Y
8524	I32	Completed copy count	Y	Y	1	65535	-8050
8525	CA16	Forms ID	Y	Y
8526	UFID_type	Spool file UFID	N	Y
8527	CA18	Active device	N	Y
8528	I32	Number of records	N	Y
8529	I32	Number of sectors	N	Y
8530	CA32	Environment file name	N	Y
8531	BIT16	Foptions	N	Y
8532	BIT16	Aoptions	N	Y
8533	I32	File open flag	N	Y
8533	I32	Broadcastable	Y	Y

Item Descriptions

The following table provides detailed descriptions of item numbers and corresponding items associated with spool file information returned by AIFSPFGET.

Table 3-32 AIFSPFGET Spool File Information Item Descriptions

Item Number	Item Name (Data Type) Release First Available Description
8501	File state (I32) Release 3.0 Returns the state of the spool file. Values and their meanings are as follows: 0 Open state (job/data input spool file being accessed) 1 Active state (job/data input spool file being created) 2 Create state (output spool file being created) 3 Defer state (defer option specified for output spool file) 4 Ready state (spool file ready to be input or output) 5 Transfer state (output spool file being transferred to remote node) 6 Print state (output spool file being printed on a device) 7 Problem state (abnormality preventing output spool file from printing) 8 Del_pending state (output spool file to be deleted after closing) 9 Spsave state (output spool file copies printed, `SPSAVE` option specified) 10 (Reserved)
8502	Priority (I32) Release 3.0 Returns the output priority of the spool file, a value in the range 0..14. Valid only for output spool files.
8503	Restartable? (I32) Release 3.0 Returns whether or not the job is restartable. `RESTART` is a parameter of the `JOB` command. This item applies only to the `$STDIN` of a job input spool file. Values and their meanings are as follows: 0 Not a restartable job 1 Restartable job
8504	Disposition (I32) Release 3.0 Returns whether the spool file is to be saved or purged after it has been printed. Values and their meanings are as follows: 1 Save after printing 2 Purge after printing
8505	Private? (I32) Release 3.0 Returns whether the spool file is a private spool file. All input spool files are created with the private option. Values and their meanings are as follows: 0 Not a private spool file 1 Private spool file
8506	Forms message? (I32) Release 3.0 Returns whether the spool file has a forms message associated with it. Valid only for output spool files. Values and their meanings are as follows: 0 No forms message associated 1 Yes forms message associated
8507	Incomplete? (I32) Release 3.0 Returns whether the spool file is incomplete. Valid only for output spool files. Values and their meanings are as follows: 0 Complete 1 Incomplete
8508	Job or data file? (I32) Release 3.0 Returns whether the spool file is a job or data file. Values and their meanings are as follows: 0 Neither a job file or a data file (for output spool file) 1 Job file 2 Data file
8509	STDLIST of aborted job? (I32) Release 3.0 Returns whether or not the spool file is the `$STDLIST` of an aborted job. Valid only for output spool files. Values and their meanings are as follows: 0 Not `$STDLIST` of an aborted job 1 `$STDLIST` of an aborted job
8510	Spool file ID (REC) Release 3.0 Returns the spool file ID in the following format: Bits (0:31) The spool file ID number in the form of 31-bit positive integer Bits (31:1) 0 for input and 1 for output spool file Record type: `spf_id_type` (Refer to appendix B.)
8511	Copies requested (I32) Release 3.0 Returns the total number of copies requested for the spool file. Valid only for output spool files.
8512	Ready date (REC) Release 3.0 Returns the calendar date when the spool file was created. All fields are 0's if the spool file is not yet `READY` or not out of the `ACTIVE`/`CREATE` state. The format returned in the 32-bit integer is the same as that returned by the `CALENDAR` intrinsic. The bits and their meanings are as follows: Bits (0:16) Unused Bits (16:7) The year of the century Bits (23:9) The day of the year Record type: `bit32` (Refer to appendix B.)
8513	Ready time (REC) Release 3.0 Returns the time (hours/minutes/seconds/tenths of seconds) when the spool file was created. All fields are 0's if the spool file is not yet ready or is not out of the active/create state. The format returned in the 32-bit integer is the same as that returned by the `CLOCK` intrinsic. The bits and their meanings are as follows: Bits (0:8) The hour of the day Bits (8:8) The minute of the hour Bits (16:8) The seconds Bits (24:8) The tenths of seconds Record type: `bit32` (Refer to appendix B.)
8514	Number of pages (I32) Release 3.0 Returns the number of pages in the spool file. A positive number indicates the actual number of pages in the spool file. A negative number indicates that the spool file has never been printed before, and the number is only an estimation. Valid only for output spool files.
8515	Restart page (I32) Release 3.0 Returns the page at which to restart if the printing of the spool file has been suspended. Valid only for output spool files.
8516	User name and account name of creator (CA32) Release 3.0 Returns the user and account name of the creator of the spool file. The first 16 bytes is the user name, and the second 16 bytes is the account name. The names should be left-justified and padded with blanks. Currently, only the first 8 bytes of each field are used.
8517	Job/session number (REC) Release 3.0 Returns the job/session number under which the spool file was created. A job/session number with a single quote (') indicates that the job or session is not current to the system, but rather that of a spool file . The format of the data returned is: Bits (0:2) Job or session (see below)? Bits (2:30) The job/session number The value of the first two bits indicates: 0 Session not current to the system (recovered) 1 Session current to the system 2 Job current to the system 3 Job not current to the system (recovered) Record type: `bit32` (Refer to appendix B.)
8518	Job name (CA16) Release 3.0 Returns the job name under which the spool file was created.
8519	File designator (CA16) Release 3.0 Returns the formal file designator of the spool file.
8520	Target device (REC) Release 3.0 Returns the destination device name or device class for the spool file. Record type: `device_name_type` (Refer to appendix B.)
8521	Device record size (REC) Release 3.0 Returns the record size of the target device of the spool file. Record type: `bit32` (Refer to appendix B.)
8522	Device type (REC) Release 3.0 Returns the device type of the target device of the spool file. Record type: `bit16` (Refer to appendix B.)
8523	Device subtype (REC) Release 3.0 Returns the device subtype of the target device of the spool file. Record type: `bit16` (Refer to appendix B.)
8524	Completed copy count (I32) Release 3.0 Returns the number of copy that has already been printed. Valid only for output spool files.
8525	Forms ID (CA16) Release 3.0 Returns the forms ID of the spool file. Valid only for output spool files.
8526	Spool file UFID (REC) Release 3.0 Returns the UFID of the spool file. Record type: `ufid_type` (Refer to appendix B.)
8527	Active device (REC) Release 3.0 Returns the name of the last device that has picked up a copy of the spool file and is currently processing the spool file. Valid only for output spool files. Record type: `device_name_type` (Refer to appendix B.)
8528	Number of records (REC) Release 3.0 Returns the number of records in the spool file. However, this number is only valid after the spool file has been created successfully. Record type: `bit32` (Refer to appendix B.)
8529	Number of sectors (I32) Release 3.0 Returns the number of sectors in the spool file.
8530	Environment File Name (CA36) Release 3.0 Returns the environment file name of the spool file. This field is valid only if the system has not been rebooted since the file was created. Valid only for output spool files.
8531	Foptions (REC) Release 3.0 Returns the Foptions of the spool file. This field is valid only if the system has not been rebooted since the file was created. Record type: `bit16` (Refer to appendix B.)
8532	Aoptions (REC) Release 3.0 Returns the Aoptions of the spool file. This field is valid only if the system has not been rebooted since the file was created. Record type: `bit16` (Refer to appendix B.)
8533	File Open Flag (I32) Release 3.0 Returns whether the spool file is currently opened by `HPFOPEN` or `FOPEN` and whether the file is opened or exclusively opened. The values and their meanings are as follows: 0 The file is not open 1 The file is opened exclusively 2 The file is opened
8534	Broadcastable (I32) Release 4.0 Returns whether the broadcastable field of an output spoolfile is set. Used to print additional copies of SPSAVE'd output spool files. Valid only for output spool files.