HPlogo 900 Series HP 3000 Computer Systems: MPE/iX Architected Interface Facility: Operating System Reference Manual > Chapter 3 Architected Interface Descriptions

AIFSPFPUT
» 

Technical documentation

Complete book in PDF
» Feedback

 » Table of Contents

 » Index

spacerspacerspacer
spacer
spacer
  		 
 

Modifies spool file information.

Syntax

                 REC            I32A          @64A           RECA

AIFSPFPUT (overall_status, itemnum_array, item_array, itemstatus_array,

             @64     REC     I32       I32A         @64A

           spf_addr, spf_id, user_id, ver_item_nums, ver_items,

                RECA

           ver_item_statuses);

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 meanings of status values.

Record type: status_type (Refer to appendix B.)

itemnum_array

32-bit signed integer array by reference (required)

An array of integers where each element is an item number indicating the operating system information to be modified. New information must be located in a data structure pointed to by the corresponding element in item_array. If n item numbers are being requested, element n+1 must be a zero to indicate 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 containing new information to be passed to the operating system. 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 value (optional)

Passes the virtual address of the spool file for which information is to be modified.

Default: nil

spf_id

record by reference (required)

Passes the ID of the spool file for which information is to be modified. If spf_addr is 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

ver_item_nums

32-bit signed integer array by reference (optional)

An array of integers where each element is an item number indicating the operating system information to be verified before proceeding with modification. Verification information must be located in a data structure pointed to by the corresponding element in ver_items. If n items are being verified, element n+1 must be a zero to indicate the end of the item list.

Default: nil

ver_items

64-bit address array by reference (optional)

An array where each element is a 64-bit address pointing to a data structure containing information to be verified against current operating system information. Information and its required data type are defined by the item number passed in the corresponding element in ver_item_nums.

Array type: globalanyptr

Default: nil

ver_item_statuses

record array by reference (optional)

An array where each element returns the status of the verification performed in the corresponding element in ver_items. A zero indicates a successful verification. 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.)

Default: nil

Operation Notes

AIFSPFPUT accepts a spool file ID or spool file address that identifies the spool file and modifies the information in the spool file directory and file label extension. If both the address and the spool file ID are provided, they are checked against each other to make sure that they match the same 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.

The three verification arrays are used to verify that the spool file entry to be updated in the SPFDIR is in the expected state. If the three verification arrays are passed, all item values specified by them are checked against the current values. The modification is performed only if all values match. The three verification arrays must all be passed or all defaulted when calling AIFSPFPUT, otherwise, an error is returned.

CAUTION: All ASCII characters to be written must be upshifted before calling AIFSPFPUT.

AIFSPFPUT Item Descriptions

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

Table 3-33 AIFSPFPUT Spool File Information Item Descriptions

Item NumberItem Name (Data Type) Put; Verify; Release First Available Description
8501File state (I32) Put: Yes; Verify: Yes; Release 3.0
 

Returns or modifies 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)

 

If a spool file is in the create state, the only legal state change is to defer or del_pending. This operation sets only an internal defer or delete pending flag. The change of file state to defer or del_pending occurs only when the file has been successfully created.

If the original state of the spool file is del_pending, changing the state of the spool file only changes the value of this field. The internal delete pending flag is not turned off.

Changing a currently printing spool file state to del_pending or defer causes the spooler to terminate the print job immediately.

Changing the spool file state to del_pending flags that the spool file is to be deleted the next time the spool file is closed. In order to have the file actually deleted, you must FOPEN and FCLOSE the file if the file was not already opened when the state was changed.

Do not change the state of an output spool file to create, open, or active.

Do not change the state of a spool file to spsave if the spool file is private.

Do not change the state of an input spool file, except for changing the state of an data input spool file from ready to del_pending.

8502Priority (I32) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies the output priority of the spool file, a value in the range 0..14. Changing the priority of a spool file causes the file to be requeued in the SPFDIR. If the priority is higher than the outfence of the target device, the spool file is printed. Valid only for output spool files.
8504Disposition (I32) Put: Yes; Verify: Yes; Release 3.0
 

Indicates whether the spool file is to be saved or purged after it has been printed. It is illegal to change the disposition of a private spool file to save. Values and their meanings are as follows:

1

Save

2

Purge

8507Incomplete? (I32) Put: Yes; Verify: Yes; Release 3.0
 

Indicates whether the spool file is incomplete by setting the "incomplete due to lack of space" flag for the specified spool file. Valid only for output spool files. Values and their meanings are as follows:

0

Complete

1

Incomplete

8509STDLIST of aborted job? (I32) Put: Yes; Verify: Yes; Release 3.0
 

Indicates whether the spool file is the $STDLIST of an aborted job by modifying the "$STDLIST of aborted job" flag. 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

8511Copies requested (I32) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies the total number of copies requested for the spool file. Valid only for output spool files. Do not modify this field if the spool file is private.
 Changing the number of copies to greater than the copies printed causes a ready spool file to be message sent to the spooler of the target device. In this case, the device is activated if it is in the idle state.
 Changing the number of copies to less than or equal to the number of completed copies (refer to item 8524) might cause the spool file to stay on the system even if the file has not been marked as spsave. Caution should be exercised when changing this field.
8512Ready date (REC) Put: Yes; Verify: Yes; Release 3.0
 

Returns or modifies the calendar date when the spool file was created. This field cannot be modified if the file is in the create or active state. The format of the 32-bit integer passed is the same as that returned by the CALENDAR intrinsic. The bits and their meanings are as follows:

Bits (0:16)

Unused (must be set to zeros)

Bits (16:7)

The year of the century

Bits (23:9)

The day of the year

 Record type: bit32 (Refer to appendix B.)
8513Ready time (REC) Put: Yes; Verify: Yes; Release 3.0
 

Returns or modifies the time (hours/minutes/seconds/tenths of seconds) when the spool file was created.This item cannot be modified if the file is in the create or active state. The format passed 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.)
8514Number of pages (I32) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies 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.
8515Restart page (I32) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies the page at which to restart if the printing of the spool file has been suspended. Negative values are not valid for this field. Valid only for output spool files.
8516User name and account name of creator (CA32) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies the user name 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 upshifted, left-justified, and padded with blanks. Currently, only the first 8 bytes of each field is used. Valid only for output spool files.
8517Job/session number (REC) Put: Yes; Verify: Yes; Release 3.0
 

Returns or modifies the job/session number under which the spool file was created. The format of the data returned is as follows:

Bits (0:2)

Job or session (see below)?

Bits (2:30)

The job/session number

 

The value of the first two bits indicates the following:

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.)
8518Job name (CA16) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies the job name under which the spool file was created. The name should be upshifted, left-justified and padded with blanks. Valid only for output spool files.
8519Spool file designator (CA16) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies the formal file designator of the spool file. The file designator should be upshifted, left-justified, and padded with blanks.
8520Target device (REC) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies the destination logical device for the spool file. It can be a device name, a device number or a device class. A device number must be in the format of ASCII character string.
 Changing the target device causes the spool file entry to be moved to the new target device's queue. Only users with SM capability can change the target device of a private spool file. The device name must be upshifted, left-justified, and padded with blanks. Valid only for output spool files.
 Record type: device_name_type (Refer to appendix B.)
8524Completed copy count (I32) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies the number of copies that have been printed already. Valid only for output spool files.
8525Forms ID (CA16) Put: Yes; Verify: Yes; Release 3.0
 Returns or modifies the forms ID of the spool file. The forms ID must be upshifted, left-justified, and padded with blanks. Valid only for output spool files.
8533Broadcastable (I32) Put:Yes; Verify: Yes; Release 4.0
 Returns or modifies the broadcastable field of the output spoolfile. Used to print additional copies of SPSAVE'd output spool files by modifying copies state field along with broadcastable field for output spool files. Valid only for output spool files.

 



AIFSPFLIST
  		 


AIFSPPGET  
Feedback to webmaster