Parameters

Edit online

The parameter definitions for CSUAACT.

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

rule_array_count
A pointer to an integer variable containing the number of elements in the rule_array variable. This value must be 1.
rule_array
The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length and must be left-aligned and padded on the right with space characters. The rule_array keywords are described in Table 1.
Table 1. Keywords for Access Control Tracking control information
Keyword Description
Function to perform (required). Setting the role_ID_length variable to 0 causes the function to operate on the default role ID.
CLRDATA Specifies to clear ACP tracking information for the role IDs identified by the role_ID parameter.
Note:
  1. No data is returned in the buffer identified by the output_data parameter.
  2. This function does not start or stop tracking information. Use the START or STOP keywords for this purpose.
  3. It is possible for some data to be gathered after CLRDATA, but before a subsequent STOP. To avoid this, use STOP before CLRDATA.
  4. This function generates an ACP query which gets logged before any tracking information is cleared.
GETDATA Specifies to return the tracking information for the role IDs identified by the role_ID parameter. This tracking information is returned into the buffer identified by the output_data parameter, provided that the buffer is large enough to receive all of the data.
Note:
  1. This function does not clear tracking information. Use CLRDATA for this purpose.
  2. This function does not stop ACP tracking. Use STOP instead.
  3. Use SIZEDATA to determine the minimum required size for the buffer identified by the output_data parameter.
GETINTVL Specifies to return the interval tracking data structure in the output_data parameter. The output_data_length parameter must indicate that enough space is available to hold the data structure. It is updated with the length of the data structure returned. For more information, read Interval tracking data structure.
GETSTATE Specifies to return the state (either enabled or not enabled) of ACP tracking for the role IDs identified by the role_ID parameter. The state is returned into the buffer identified by the output_data parameter, provided that the buffer is large enough to receive all of the data.
Note: This function does not start or stop ACP tracking. Use START or STOP instead.
SIZEDATA Specifies to return the size of the data in bytes that GETDATA would return as a single integer value into the output_data_length variable.
Note:
  1. No data is returned in the buffer identified by the output_data parameter.
  2. The output_data_length variable can be greater on output than on input.
  3. Provide the same list of role IDs to be used for GETDATA.
START Specifies to start ACP tracking for the role IDs identified by the role_ID parameter.
Note:
  1. No data is returned in the buffer identified by the output_data parameter.
  2. Use of this function for a role ID that is being tracked has no effect and does not cause an error or warning.
STOP Specifies to stop ACP tracking for the role IDs identified by the role_ID parameter.
Note:
  1. No data is returned in the buffer identified by the output_data parameter.
  2. Use of this keyword on a role ID that is not being tracked has no effect and does not cause an error or warning.
  3. ACP tracking stops after the ACP check for the required commands of this verb are recorded for the appropriate role ID.
role_ID_length
The role_ID_length parameter is a pointer to an integer variable containing the number of bytes of data in the role_ID variable. This value must be greater than or equal to 0 and a multiple of 8.
Note: Setting the role_ID_length variable to 0 causes the function to operate on the default role ID.
role_ID
This parameter is a pointer to a string variable containing an optional array of role IDs of the role definitions to process. The role IDs are 8 bytes in length and must be left-aligned and padded on the right with space characters.
output_data_length
This parameter is a pointer to an integer variable containing the number of bytes of data in the output_data variable. For keyword SIZEDATA, this value is allowed to be less on input than on output since no data is returned in the buffer identified by the output_data parameter. Otherwise, set this value to at least the number of data bytes to be returned in that buffer.
output_data
The output_data parameter is a pointer to a string variable containing data returned by the verb. The size and content of the output data depends on the function to perform based on the rule array. Only rule array keywords GETDATA and GETSTATE return data in this variable (buffer). Keyword SIZEDATA does not return any data in this buffer, even if the returned output_data_length variable is greater than 0.
The GETSTATE option returns a concatenation of role tracking data headers, one for each role ID identified by the role_ID parameter. Refer to Table 2. No additional data follows the header for GETSTATE.
Table 2. Role tracking data header format
Offset (bytes) Length (bytes) Description
00 02 Role tracking data (RTD) header version (X'0100').
02 02 RTD length in bytes (big endian): rtdln. Length includes this header (16 bytes) + length of data that follows the header, if any.
04 08 Role ID of role tracking data
12 01 Role tracking flag byte for the role ID (value at offset 4)
Value
Meaning
B'xxxx xxx0'
Tracking is not enabled.
B'0000 0001'
Tracking is enabled.

All unused bits are reserved and must be zero.
13 03 Reserved, binary zero.
Note:
  1. For GETDATA, the returned output_data is a concatenation of a role tracking data header and an ACP list pair, one for each role ID identified by the role_ID parameter.
  2. For GETSTATE, the returned output_data is a concatenation of role tracking data headers, one for each role ID identified by the role_ID parameter.
The GETDATA option returns a role tracking data header for each role ID, with an additional ACP list concatenated to each header. Refer to Table 1. Table 3 provides the format of the output returned by the GETDATA option.
Table 3. GETDATA output_data format
Offset (bytes) Length (bytes) Description
role_id 1 of n, where n = 1 for role_ID_length = 0. Otherwise n = role_ID_length / 8.
00 02 Role tracking data (RTD) header version (X'0100').
02 02 RTD length in bytes (big endian): rtdln#1. Length includes this header (16 bytes) + length of ACP list structure.
04 08 Role ID of role tracking data
12 01 Role tracking flag byte for the role ID (value at offset 4)
Value
Meaning
B'xxxx xxx0'
Tracking is not enabled.
B'0000 0001'
Tracking is enabled.

All unused bits are reserved and must be zero.
13 03 Reserved, binary zero.
16 rtdln#1 - 16 Access-control-point list structure for role ID 1. Refer to Table 1.

The meaning of each bit valued in the bit-map data segments of the ACP list structure has the following meaning for role tracking data:

Value
Meaning
B'0'
No recorded access attempt has been made.
B'1'
This ACP has had at least one access attempt while being tracked. The value does not indicate the success of any access attempt.
Note:
  1. Use the Access Control Maintenance (CSUAACM) verb with the GET-ROLE rule-array keyword to determine which offsets this role ID has enabled. Compare the CSUAACM list of enabled ACPs to the tracking list of the role ID to determine which ACP access attempts were successful.
  2. The gathering of data for a given role ID can be impacted by multiple STARTs and STOPs. if CLRDATA is not performed between a STOP and a START.
role_ID 2 of n, for role_ID_length ≥ 2*8 where n = role_ID_length / 8
rtdln#1 02 RTD header version.
rtdln#1 + 02 02 RTD overall length in bytes (big endian): rtdln#2
rtdln#1 + 04 08 Role ID of role tracking data.
rtdln#1 + 12 01 Role tracking flag byte for role ID (value at offset rtdln#n-1 + 4).
rtdln#1 + 13 03 Reserved, binary zero.
rtdln#1 + 16 rtdln#n - 16 Access-control-point list structure for role ID n
Note:
  1. For GETDATA, the returned output_data is a concatenation of a role tracking data header and ACP list pair, one for each role ID identified by the role_ID parameter.
  2. All integer values returned in the output_data variable are in big-endian format.
The GETSTATE option returns a concatenation of role tracking data headers, one for each role ID identified by the role_ID parameter. Refer to Table 4. No additional data follows the header for GETSTATE.
Table 4. GETSTATE output_data format
Offset (bytes) Length (bytes) Description
00 02 Role tracking data (RTD) header version (X'0100').
02 02 RTD structure length in bytes (big endian). Length includes this header (16 bytes) + length of data that follows the header (zero for GETSTATE).
04 08 Role ID of role tracking data
12 01 Role tracking flag byte for the role ID (value at offset 4)
Value
Meaning
B'xxxx xxx0'
Tracking is not enabled.
B'0000 0001'
Tracking is enabled.

All unused bits are reserved and must be zero.
13 03 Reserved, binary zero.
Note: For GETSTATE, the returned output_data is a concatenation of role tracking data headers, one for each role ID identified by the role_ID parameter.
reserved1_length
The reserved1_length parameter is a pointer to an integer variable containing the number of bytes of data in the reserved1 variable. This value must be zero.
reserved1
The reserved1 parameter is a pointer to a string variable. This parameter is reserved for future use.
reserved2_length
The reserved2_length parameter is a pointer to an integer variable containing the number of bytes of data in the reserved2 variable. This value must be zero.
reserved2
The reserved2 parameter is a pointer to a string variable. This parameter is reserved for future use.