|
|
|
Returns system information (for example, PIDs and UFIDs) to be used as input
keys by other AIFs to access more detailed information.
Syntax
REC I32 A
AIFSYSWIDEGET ( overall_status, aif_area, return_array1,
A I32 I32A
return_array2, num_entries, itemnum_array,
@64A RECA REC I32
item_array, itemstatus_array, search_key, user_id,
@64
buffer_ptr );
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.)
- aif_area
- 32-bit signed integer by value (required)
Passes a value indicating the information area (for example, process
information or file information) for which system wide information is
desired. Values indicating the desired information area are specified in
Table 3-37 "AIFSYSWIDEGET Parameter
Information".
- return_array1
- array by reference (optional)
Returns system information keys (for example, PIDs and UFIDs). The keys
can also be used by other AIFs to access more detailed information
associated with the key. The size and type of key is dependent on the
information area specified in aif_area. The size and
type of keys are specified in Table
3-37 "AIFSYSWIDEGET Parameter Information". If a nil address (the
default value) is passed, no keys are returned.
Make the array large enough to hold the largest number of keys that you
expect to receive.
Array type: (Refer to Table 3-37
"AIFSYSWIDEGET Parameter Information{.)
Default: nil
- return_array2
- array by reference (optional)
Returns system information keys (for example, PIDs, UFIDs). The keys can
also be used by other AIFs to access more detailed information
associated with the key. The size and type of a key is dependent on the
information area specified in aif_area. The size and
type of keys are specified in Table
3-37 "AIFSYSWIDEGET Parameter Information". If a nil address (the
default value) is passed, no keys are returned.
Make the array large enough to hold the largest number of keys that you
expect to receive.
Array type: (Refer to Table 3-37
"AIFSYSWIDEGET Parameter Information".)
Default: nil
- num_entries
- 32-bit signed integer by reference (required)
On input, the number of entries is the number of elements in
return_array1 or return_array2. On
output, num_entries represents the number of elements
returned in return_array1, return_array2,
or the buffer pointed to by buffer_ptr. If
return_array1, return_array2, and
buffer_ptr were nil pointers, the returned value would
be the number of instances meeting the specified item criteria.
Note that num_entries is only used on input when
return_array1 or return_array2 are
specified, but it is used on output when either
return_array1, return_array2, or
buffer_ptr are specified.
- itemnum_array
- 32-bit signed integer array by reference (optional)
An array of integers where each element is an item number indicating the
class of selection criteria located in the corresponding element in
item_array. Valid items depend upon the information area
specified in aif_area. For example, if information is
desired about processes, then the criteria may be process-state,
capabilities, and so on. If n criteria are specified,
element n+1 must be a zero to indicate the end of the
element list.
Refer to the AIFSYSWIDEGET Criteria Item Description tables for
descriptions of item numbers and their corresponding items.
Default: nil
- item_array
- 64-bit address array by reference (optional)
An array where each element is a 64-bit address pointing to a data
structure containing the specific value of the criteria item specified
in itemnum_array.
Refer to the AIFSYSWIDEGET Criteria Item Description tables for
descriptions of item numbers and their corresponding items.
Array type: globalanyptr
Default: nil
- itemstatus_array
- record array by reference (optional)
An array where each element returns the status about each of the
selection criteria located in the corresponding element in
item_array. For example, an error condition is returned
if a criteria value in the corresponding element in
item_array is incorrect, or if the criteria is no longer
supported. (Refer to appendix A for status descriptions.)
Array type: status_type (Refer to appendix B.)
Default: nil
- search_key
- record by reference (optional)
In the event that return_array1 and
return_array2 are not large enough to contain all the
returned values of the specified criteria, a search key is returned. On
a subsequent call to AIFSYSWIDEGET, the search key eliminates
duplicating values that have already been returned. No search key is
returned for spool files.
The initialization value of search_key is determined by
the information area specified in aif_area prior to the
first call to AIFSYSWIDEGET. The appropriate initialization
values are specified in Table 3-37
"AIFSYSWIDEGET Parameter Information".
Record type: search_key_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
- buffer_ptr
- 64-bit address by reference (optional)
A long pointer to a buffer which is sufficient to hold the items
requested. The size of this buffer (in bytes) must be specified in the
first four bytes of the buffer. On return from AIFSYSWIDEGET,
these four bytes will contain the actual number of bytes returned.
See the buffer_type declaration in appendix B for a suggestion
on one way to define this buffer when retrieving a list of HFS
pathnames.
Operation Notes
The following information is specified in
Table 3-37 "AIFSYSWIDEGET Parameter Information":
- A value corresponding to each specified information area to be passed in
the aif_area parameter.
- The data type required to be passed in return_array1
and/or return_array2 that corresponds to the information
area specified in the aif_area parameter.
- The data type and initialization value to be passed in the
search_key parameter. The search_key for
ascii strings must be initialized to blanks.
Table 3-37 AIFSYSWIDEGET Parameter Information
| Area\ Value |
Area\ Name |
return_array1 Type |
return_array2 Type |
search_key Type Initial Value |
| 1000 |
Job/session information |
Job/session key (jskey_type) |
Job/session number (jsnum_type) |
(I32) 0 |
| 2000 |
Process information |
PID (longint_type) |
None |
(I32) 0 |
| 5000 |
File information |
MPE Files (item 5001) UFIDs (UFID_type) |
MPE Files (item 5001) File name (filename_type) |
MPE Files (item 5001) Filename (filename_type) Blanks |
|
|
MPE and HFS Files (item 5036) Path identifier (path_identifier) |
MPE and HFS Files (item 5036) Buffer Information (buffer_info_type) |
MPE and HFS Files (item 5036) Pathname (max_pathname_type) Blanks |
| 6000 |
Accounting information |
None |
Directory name (directory_name_type) |
directory_name_type Blanks |
| 8000 |
Spool file information |
Spool file address (@64) |
Spool file number (spf_id_type) |
Not applicable |
| 13000 |
Device |
LDEV Number (I32) |
Device Key (ufid_type) |
(I32) 0 |
| 13500 |
Device Class |
Device Class Name (C16) |
Device Class Key (I32) |
(I32) 0 |
| 14000 |
Console Reply information |
Reply request ID (I32) |
None |
(I32) 0 |
| 19000 |
Workgroup information |
Workgroup Names (CA256) |
None |
key_wg_type (0) |
Refer to appendix B for descriptions of the indicated data types.
If a criteria item is of type integer, a range of values can be requested by
passing the same criteria item number in consecutive elements of
itemnum_array, and passing the lower and upper limits in the
corresponding consecutive elements of item_array. The first
value must be the lower limit (>=) and the second value the upper limit
(<=).
Criteria items that have range capability are noted in the tables of
AIFSYSWIDEGET criteria item descriptions.
Device Class Area The "Device Key" (item 13500) is the UFID of the
selected device file. The "Device Class Key" (item 13000) is the class index
to the Device Class Table. This is a faster key to access device class
information than the Device Class Name.
File Area If you specify both item 5001 (MPE file name) and item 5036
(HFS pathname), item 5036 will be used when selecting files.
Item 5036, Return array 1 (Path Identifier)
If you are interested only in MPE files, the UFID key is the faster key to
access file information using the AIFFILEGGET/PUT AIFs. If
you are interested in all files including both MPE syntax and HFS syntax files,
the path identifier is the faster key to access file information. The path
identifier contains the file UFID, link ID, and parent UFID. These items
provide the necessary information to the HFS directory services to provide
fast access.
Note that throughout the file related AIFs, UFID keys and UFID items are still
valid for HFS syntax as well as MPE syntax files since a UFID is still unique
for every file on the system. However, the UFID alone is not enough
information to identify a unique filename for an HFS syntax file since the
filename is no longer kept in the file label and since multiple file links
will be supported in the future.
Item 5036, Return array 2 (Buffer Information)
Return array 2 is defined as an array of entries where each entry contains the
following:
- Buffer offset - Buffer_ptr relative offset to pathname.
- Pathname length - Length of the pathname. The length does not include
the NULL terminator.
The information in this return array can be used to index directly into the
buffer of pathnames if you wish to perform binary searches for example. It can
also be used in conjunction with a Pascal STRMOVE to easily retrieve a
pathname from the buffer.
The following diagram illustrates this:
Buffer_ptr
V
0 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
----------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|length| / F N A M E \0| / D I R / N A M E \0|
|---------------------------------------------------------
\\ etc. //
| |
-----------------------------------------------------------
Return Array 2
-------------
| offset = 4 |
1 |. . . . . . .|
| length = 6 |
|-------------|
| offset = 11 |
2 |. . . . . . .|
| length = 9 |
|-------------|
|/////////////|
|/////////////|
-------------
 |
NOTE: Although chaining (that is, calling AIFSYSWIDEGET
multiple times passing it a search key) is supported for item 5036, it is
not recommended for best performance results. It will be much faster to
retrieve as many files as possible with fewer calls to
AIFSYSWIDEGET.
|
Operation Notes - HFS Pathname Syntax
AIFSYSWIDEGET will accept a generic pathname using the same
wildcarding as the LISTFILE command. See the description of the
LISTFILE command in the MPE/iX Reference Supplement
(32650-90353) for more information.
Below are some of the rules defining the syntax of an HFS pathname.
- Directory names end in a slash (/). This includes MPE accounts, MPE
groups, and HFS directories.
- A filename can have a maximum of 255 characters.
- If the fileset begins with a slash (/), then the pathname is assumed to
be an absolute pathname.
- If the fileset begins with a ./, then the pathname is assumed to be a
relative pathname.
Operation Notes - HFS Directory Security
With the new AIFSYSWIDEGET HFS file item, you must have the
appropriate security access rights to traverse (TD - traverse directory) and
read (RD - read directory) directories protected by an ACD. This is because
the lower level directory traversal routines enforce security checking. This
will enable you to provide your own LISTF type of application and
take advantage of the system security checking without having to implement
your own security routines.
System managers are always granted all access to files and hierarchical
directories protected by ACDs. If your process does not already have System
Manager (SM) capability, you can easily retrieve SM capability for the process
by calling AIFPROCPUT with item 2095 to alter user capabilities.
See the description of the ALTSEC command in the MPE/iX Reference
Supplement (32650-90353) and Controlling System Activity
(32650-90155) for more information on file ACDs and system security.
Operation Notes - Handling Directory Traversal Errors
Starting in release 5.0, users have more flexibility in handling errors
detected during directory traversal (valid only with HFS traversal). A new
item, 5050, has been added to allow users to ignore non-fatal directory errors
which will not prevent them from continuing traversal. When a non-fatal error
is detected and this item is true, the directory traversal will continue
without reporting any error to the user, and the file for which an error was
detected will not be returned to the user's buffer.
If the user does not wish to ignore the error, then an error will be returned
to the user, and the file for which the error was detected will be returned in
the SEARCH KEY parameter. The user's buffer and return arrays would also
contain all the files up until the point where the error was detected. The
user can then handle the error if they wish, and then call
AIFSYSWIDEGET again with the SEARCH KEY to continue the directory
traversal starting with the NEXT file.
Some examples of non-fatal errors are bad UFIDs and lack of the appropriate
security access rights (for example, no TD access).
|
|
NOTE: Some errors (for example, bad UFID) will now only be detected
if you pass in criteria such as record type or file type which requires
AIFSYSWIDEGET to retrieve the file label pointer and look in the
file label for a matching criteria. This is like doing a LISTFILE
as compared to a LISTFILE,-3 (for example, LISTFILE,-3
will report an error when there is a bad UFID, but LISTFILE will
not). This change will improve performance since there is no need to go to
the file label in all cases.
|
Programming Examples
Following are programming examples for AIFSYSWIDEGET.
Example One - Job Numbers
Following is an example of a call to AIFSYSWIDEGET to obtain a list
of job numbers of all jobs on the system that are suspended.
Procedure AIFSYSWIDEGET (
overall_status,
aif_area, = [ 1000 {Job/Sessions} ]
,
return_array2, = [ array of integer [1..n] ]
num_entries, = [ number of elements n ]
itemnum_array, = [ [1] = 1002 {JOBSTATE},
[2] = 0 {TERMINATOR} ]
item_array, = [ [1] = 4 {SUSPENDED} ]
itemstatus_array,
, { no search key }
user_id );
Example Two - PIDs of CI processes
Following is an example of a call to AIFSYSWIDEGET to obtain a list
of PIDs of all CI processes. A search key is returned if there are more PIDs
than the number of elements in the return_array1.
Procedure AIFSYSWIDEGET (
overall_status,
aif_area, = [ 2000 {PROCESS} ]
return_array1, = [ array of longint_type [1..n] ]
,
num_entries, = [ number of elements n ]
itemnum_array, = [ [1] = 2151 {Process Type},
[2] = 0 {TERMINATOR} ]
item_array, = [ [1] = 2 {MAIN} ]
itemstatus_array,
search_key, = [ initialize before first call ]
user_id );
Example Three - Number of output spool files
Following is an example of a call to AIFSYSWIDEGET to obtain the
number of output spool files with priority greater than 7.
Procedure AIFSYSWIDEGET (
overall_status,
aif_area, = [ 8000 {SPOOL FILES} ]
,
,
num_entries, = [ 0 ]
itemnum_array, = [ [1] = 8502 {Output Priority},
[2] = 8502,
[3] = 0 ]
item_array, = [ [1] = 8,
[2] = 14 ]
itemstatus_array,
, { no search key }
user_id );
Example Four - List of accounts with SM capability
Following is an example of a call to AIFSYSWIDEGET to obtain a list
of all accounts with SM capability:
Procedure AIFSYSWIDEGET (
overall_status,
aif_area, = [ 6000 {ACCOUNTING} ]
,
return_array2, = [ array of directory name types [1..n] ]
num_entries, = [ number of elements n ]
itemnum_array, = [ [1] = 6203 {Account Capabilities},
[2] = 0 ]
item_array, = [ [1] = an integer with bit16 enabled ]
itemstatus_array,
, { no search key }
user_id );
Example Five - Configured devices for a device class
Following is an example of a call to AIFSYSWIDEGET to obtain a list
of configured devices for a device class.
Procedure AIFSYSWIDEGET (
overall_status,
aif_area, = [ 13000 {DEVICE} ]
return_array1, = [ array of integer {list of LDEV numbers} ]
,
num_array_entries, = [ number of elements in return_array ]
itemnum_array, = [ [1] = 13002 {device class} ]
item_array, = [ [1] = TERM ]
item_status_array,
search_key,
user_id );
Example Six - Configured devices for a range of LDEV numbers
Following is an example of a call to AIFSYSWIDEGET to obtain a list
of configured devices for a range of LDEV numbers.
Procedure AIFSYSWIDEGET (
overall_status,
aif_area, = [ 13000 {DEVICE} ]
return_array1, = [ array of integer {list of LDEV numbers} ]
,
num_array_entries, = [ number of elements in return_array ]
itemnum_array, = [ [1] = 13002,
[2] = 13001 {a range of LDEV numbers} ]
item_array, = [ [1] = 1,
[2] = 20 {from LDEV #1 to #20} ]
item_status_array,
, { no search key }
user_id );
Example Seven - Configured devices on the system
Following is an example of a call to AIFSYSWIDEGET to obtain a list
of configured devices on the system.
Procedure AIFSYSWIDEGET (
overall_status,
aif_area, = [ 13000 {DEVICE} ]
return_array1, = [ character array {list of device classes} ]
, { do not want list of device keys }
num_array_entries, = [ number of elements in return_array ]
, { no itennum }
, { no item_array }
, { no item_status_array }
search_key, { initialize to zero or blanks before the 1st
call }
user_id );
Example Eight - Device classes for a LDEV number
Following is an example of a call to AIFSYSWIDEGET to obtain a list
of device classes for a LDEV number.
Procedure AIFSYSWIDEGET (
overall_status,
aif_area, = [ 13000 {DEVICE} ]
return_array1, = [ array of integer {list of LDEV numbers} ]
return_array2, = [ array of integer {the corresponding fast
device keys} ]
num_array_entries, = [ number of elements in return_array ]
itemnum_array, = [ [1] = 13501,
[2] = 0 {LDEV} ]
item_array, = [ [1] = 6 {LDEV 6} ]
item_status_array,
, { no search key }
user_id );
|
|
NOTE: For more programming examples of AIFSYSWIDEGET refer
to Appendix C.
|
|
