 |
» |
|
|
|
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 A
AIFSYSWIDEGET (overall_status, aif_area, return_array1, return_array2,
I32 I32A @64A
num_entries, itemnum_array, item_array,
RECA REC I32
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 SyntaxAIFSYSWIDEGET 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 SecurityWith 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 ErrorsStarting 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 NumbersFollowing 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 processesFollowing 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 filesFollowing 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 capabilityFollowing 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 classFollowing 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 numbersFollowing 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 systemFollowing 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 numberFollowing 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. | | | | |
|
