Copyright BM Corp. 2014. All rights reserved.

595
Appendix A. PoIicy ruIe syntax definitions
This appendix provides the syntax definitions and SQL expressions for the GPFS policy rules.
A
596 SONAS mplementation Guide
PoIicy ruIe syntax definitions
The GPFS policy rules follow these syntax definitions:
DIRECTORIES_PLUS
ndicates that non-regular file objects such as directories and symbolic links, are included in
the list. f not specified, only ordinary data files are included in the candidate lists.
DELETE
dentifies a file deletion rule. A file that matches this rule becomes a candidate for deletion.
EXCLUDE
dentifies a file exclusion rule. A file that matches this rule is excluded from further rule
evaluation. When specified in a LST rule, EXCLUDE indicates that any matching files be
excluded from the list.
EXTERNAL LIST ListName
Defines an external list. This rule does not match files. t provides the binding between the
lists generated by regular LST rules with a matching ListName and the external program that
you want to run, using these lists as input.
EXTERNAL POOL PoolName
Defines an external file system pool. This rule does not match files, but rather serves to define
the binding between the policy language and the external storage manager that implements
the external storage.
FOR FILESET (FilesetName[,FilesetName]...)
Specifies that the rule should apply only to files within the specified file sets.
FROM POOL FromPoolName
Specifies the name of the source pool from which files are candidates for migration.
LIMIT(OccupancyPercentage)
Limits the creation of data in a file system pool. f it is determined that transferring the file to
the specified file system pool would exceed the specified occupancy percentage for that pool,
GPFS skips the rule and the policy engine looks for the next rule that might match.
For testing or planning purposes, and when using the command with the -T
validate or -T details option, it is acceptable to specify a LMT that is larger than 100%.
LIST ListName
dentifies a file list generation rule. A given file might match more than one list rule, but is
included in a given list only once. ListName provides the binding to an EXTERNAL LST rule
that specifies the executable program to use when processing the generated list.
MIGRATE
dentifies a file migration rule. A file that matches this rule becomes a candidate for migration
to the file system pool specified by the TO POOL clause.
Appendix A. Policy rule syntax definitions 597
OPTS 'OptionsString ...'
Specifies optional parameters to be passed to the external program defined with the EXEC
clause. OptionsString is not interpreted by the GPFS policy engine.
REPLICATE (DataRepIication)
Overrides the default data replication factor. This value should be specified as 1 or 2.
RESTORE TO POOL PooIName
dentifies a file restore rule. When a file is restored using the gpfs_fputattrswithpathname()
subroutine, this rule allows you to match files against their saved attributes rather than the
current file attributes.
RULE ['RuIeName']
nitiates the rule statement. RuleName identifies the rule and is used in diagnostic messages.
SET POOL PooIName
dentifies an initial file placement rule. PoolName specifies the name of the file system pool
where all of the files that match the rule criteria will be placed.
SHOW (['String'] SqIExpression)
nserts the character representation of the evaluated SQL expression SqlExpression into the
candidate list created by the rule when it deals with external file system pools. String is a
literal value that is echoed back.
This clause has no effect in matching files, but can be used to define additional attributes to
be exported with the candidate file lists.
SIZE(numeric-sqI-expression)
s an optional clause of any MGRATE, DELETE, or LST rules that are used for choosing
candidate files. numeric-sql-expression specifies what is to be considered as the size of the
file when calculating the total amount of data to be passed to a user script. The default is
KB_ALLOCATED.
SIZE sum-number
s an optional clause of the EXTERNAL POOL and EXTERNAL LST rules. Specify
sum_number as a numeric constant.
THRESHOLD (HighPercentage[,LowPercentage[,PremigratePercentage]])
Controls migration and deletion based on the storage utilization of the file system pool, which
is the percent of assigned storage that is occupied. THRESHOLD is used in conjunction with
the FROM POOL clause.
HighPercentage
ndicates that the rule is to be applied only if the occupancy percentage of the named file
system pool is greater than or equal to the HighPercentage value. Specify a nonnegative
integer in the range 0 to 100.
LowPercentage
598 SONAS mplementation Guide
ndicates that MGRATE and DELETE rules are applied until the occupancy percentage of
the named file system pool is reduced to less than or equal to the LowPercentage value.
Specify a nonnegative integer in the range 0 to 100. The default is 0.
PremigratePercentage
Defines an occupancy percentage of a file system pool that is below the lower limit. Files
that lie between the lower limit LowPercentage and the pre-migrate limit
PremigratePercentage are copied and become dual-resident in both the internal GPFS file
system pool and the designated external file system pool. This option allows the system to
free up space quickly by simply deleting premigrated files if the pool becomes full. Specify
a nonnegative integer in the range 0 to LowPercentage. The default is the same value as
LowPercentage.
Note that this option only applies when migrating to the external file system pool.
THRESHOLD (Resource_cIass)
Specifies which kind of capacity-managed resources are associated with ListName.
Supported values are:
FILESET_QUOTAS
ndicates that the LST rule uses the occupancy percentage of file set quotas when using the
threshold rule.
GROUP_QUOTAS
ndicates that the LST rule uses the occupancy percentage of group quotas when using the
threshold rule.
POOL_CAPACITIES
f threshold is not specified in the EXTERNAL LST rule but is specified in the LST rule, the
resource class is POOL_CAPACTES, by default. This indicates that the LST rule will use
the occupancy percentage of the file system pool when using the threshold rule. t is the
default.
USER_QUOTAS
ndicates that the LST rule uses the occupancy percentage of user quotas when using the
threshold rule.
TO POOL ToPooIName
Specifies the name of the file system pool to which all of the files that match the rule criteria
are migrated.
WEIGHT (WeightExpression)
Establishes an order on the matching files. Specifies an SQL expression with a numeric value
that can be converted to a double precision floating point number. The expression can refer to
any of the file attributes and can include any constants and any of the available SQL
operators or built-in functions.
WHEN (TimeBooIeanExpression)
Specifies an SQL expression that evaluates to TRUE or FALSE, depending only on the SQL
built-in variable CURRENT_TMESTAMP. f the WHEN clause is present and
TimeBooleanExpression evaluates to FALSE, the rule is skipped.
Appendix A. Policy rule syntax definitions 599
The GPFS command assigns the CURRENT_TMESTAMP once, when it
begins processing, using either the actual UTC time and date or the date specified with the -D
option.
WHERE SqIExpression
Specifies an SQL expression that can reference file attributes as SQL variables, functions,
and operators. Some attributes are not available to all rules. WHERE compares the file
attributes specified in the rule with the attributes of the file being created.
SqlExpression must be an expression that evaluates to TRUE or FALSE, but can be any
combination of standard SQL syntax expressions, including built-in functions.
You can omit the WHERE clause entirely. t is equivalent to writing WHERE TRUE. When
used, the WHERE clause must be the last clause of the rule.
SQL expressions for poIicy ruIes
Several available clauses in the GPFS policy rules use SQL expressions. You can reference
file attributes as SQL variables and combine them with SQL functions an operators.
Depending on the clause, the SQL expression must evaluate to either TRUE or FALSE, a
numeric value, or a character string. Not all file attributes are available to all rules.
Using fiIe attributes
The following file attributes can be used in SQL expressions specified with the WHERE,
WEGHT and SHOW clauses:
ACCESS_TIME
Specifies an SQL timestamp value for the date and time that the file was last accessed, which
in POSX is the atime variable.
BLOCKSIZE
Specifies the size, in bytes, of each block of the file.
CHANGE_TIME
Specifies an SQL timestamp value for the date and time that the file metadata was last
changed, which in POSX is the ctime variable.
CREATION_TIME
Specifies the SQL timestamp value that is assigned when a file is created.
DEVICE_ID
Specifies the D of the device that contains the directory entry.
FILE_SIZE
Specifies the size of the file, in bytes.
600 SONAS mplementation Guide
FILESET_NAME
Specifies the file set where the path name for the files is located, or is to be created.
Note that using the FOR FLESET clause has the same effect, and is more efficient to
evaluate.
GENERATION
Specifies a number that is incrementally increased whenever an NODE number is reused.
GROUP_ID
Specifies the numeric group D of the file's group.
INODE
Specifies the file's i-node number.
KB_ALLOCATED
Specifies the number of kilobytes of disk space allocated for the file data.
MODE
Specifies a file mode.
MISC_ATTRIBUTES
Specifies a variety of miscellaneous file attributes. The value is a concatenated string of
attributes, with the following definitions:
A - archive
c - compressed
e - encrypted
F - regular data file
D - directory
Note: To match all directories, use 09/07/28 as a wildcard.
H - hidden
i - not indexed by content
L - symbolic link
o - offline
O - other, meaning not F, D, nor L.
Note: O might be used for a device or named pipe.
M - co-managed
2 - data blocks are replicated
Appendix A. Policy rule syntax definitions 601
- some data blocks might be ill-placed
J - some data blocks might by ill-replicated
p - reparse point
r - has streams
R - read-only
s - sparse file
S - system
t - temporary
U - trunc-managed
V - read-managed
W - write-managed
X - immutability
MODIFICATION_SNAPID
Specifies the integer D of the snapshot after which the file was last changed. The value is
normally derived with the SNAPD() built-in function, which assigns integer values to GPFS
snapshot names. This attribute allows policy rules to select files that have been modified after
a given snapshot image was taken.
MODIFICATION_TIME
Specifies an SQL timestamp value for the date and time that the file data was last modified,
which in POSX is the mtime variable.
NAME
Specifies the name of a file. When used in SQL LKE comparisons, two wildcard characters
are recognized:
A percent sign (%) in the name represents zero or more characters.
An underscore (_) in the name to represents one single-byte or multibyte character.
NLINK
Specifies the number of hard links to the file.
PATH_NAME
Specifies a path for the file.
POOL_NAME
Specifies the file system pool where the file data resides.
Note that using the FROM POOL clause has the same effect, and is generally preferable.
602 SONAS mplementation Guide
RDEVICE_ID
Specifies the device type for a device.
USER_ID
Specifies the numeric user D of the owner of the file.
- When file attributes are referenced in initial placement rules, only the following
attributes are valid: NAME, USER_D, GROUP_D, and FLESET_NAME. The
placement rules, like all rules with a WHERE clause, might also reference the current
date and current time and use them to control matching.
- When file attributes are used for restoring files, the attribute values that are used for a
file correspond to the file's attributes at the time of its backup, not to the attribute values
of the restored file.
Using buiIt-in functions
With GPFS, you can use built-in functions in predicates such as comparison, between, in and
like, mathematical value expressions, and boolean, string and numeric literals. These
functions are organized into the following categories:
Extended attribute functions
You can use these functions to support access to the extended attributes of a file, and to
support conversion of values to the supported SQL data types:
XATTR(extended-attribute-name [, start [, Iength]])
Returns the value of a substring of the extended attribute that is named by its argument as an
SQL VARCHAR value, where:
extended-attribute-name
Specifies any SQL expression that evaluates to a character string value. f the named
extended attribute does not exist, XATTR returns the special SQL value NULL.
start
s the optional starting position within the extended attribute value. The default is 1.
length
s the optional length, in bytes, of the extended attribute value to return. The default is the
number of bytes from the start to the end of the extended attribute string.
XATTR (name,i,k) == SUBSTR(XATTR(name),i,k).
Some extended attribute values represent numbers or timestamps as decimal or binary
strings. Use the TMESTAMP, XATTR_FLOAT, or XATTR_NTEGER function to convert
extended attributes to SQL numeric or timestamp values:
XATTR_FLOAT(extended-attribute-name [, start [, length, [, conversion_option ]]])
Returns the value of a substring of the extended attribute that is named by its argument,
converted to an SQL double floating-point value, where:
Appendix A. Policy rule syntax definitions 603
extended-attribute-name
Specifies any SQL expression that evaluates to a character string value. f the named
extended attribute does not exist, XATTR returns the special SQL value NULL.
start
s the optional starting position within the extended attribute value. The default is 1.
length
s the optional length, in bytes, of the extended attribute value to return. The default is the
number of bytes from the start to the end of the extended attribute string. You can specify
length as -1 to reach from the start to the end of the extended attribute string.
conversion_option
Specifies how the bytes are to be converted to a floating-point value. Supported options
include:
- BG_ENDAN_DOUBLE or BD - a signed binary representation, EEE floating, sign +
11 bit exponent + fraction. t is the default when processing on a "big endian host OS,
such as AX on BM PowerPC.
- BG_ENDAN_SNGLE or BS - EEE floating, sign + 8-bit exponent + fraction.
- LTTLE_ENDAN_DOUBLE or LD - bytewise-reversed binary representation. t is the
default when processing on a "little endian host OS, such as Linux on ntel x86.
- LTTLE_ENDAN_SNGLE or LS - bytewise-reversed binary representation.
- DECMAL - the conventional SQL character string representation of a floating-point
value.
Notes:
Any prefix of a conversion name can be specified instead of spelling out the whole name. The
first match against the list of supported options is used; for example, L matches
LTTLE_ENDAN_DOUBLE.
f the extended attribute does not exist, if the selected substring has a length of 0, or if the
selected bytes cannot be converted to a floating-point value, then the function returns the
special SQL value NULL.
XATTR_INTEGER(extended-attribute-name [, start [, Iength, [, conversion_option ]]])
Returns the value, or substring, of the extended attribute named by its argument, converted to
an SQL LARGENT value, where:
extended-attribute-name
Specifies any SQL expression that evaluates to a character string value. f the named
extended attribute does not exist, XATTR returns the special SQL value NULL.
start
s the optional starting position within the extended attribute value. The default is 1.]
length
s the optional length, in bytes, of the extended attribute value to return. The default is
the number of bytes from the start to the end of the extended attribute string. You can
specify length as -1 to reach from the start to the end of the extended attribute string.
604 SONAS mplementation Guide
conversion_option
Specifies how the bytes are to be converted to a LARGENT value. Supported options
include:
- BG_ENDAN - a signed binary representation, most significant byte first. t is the
default when processing on a "big endian host OS, such as AX on PowerPC.
- LTTLE_ENDAN - bytewise-reversed binary representation. t is the default when
processing on a "little endian host OS, such as Linux on ntel x86.
- DECMAL - the conventional SQL character string representation of an integer value.
Notes:
Any prefix of a conversion name can be specified instead of spelling out the whole name; for
example, B, L, or D.
f the extended attribute does not exist, if the selected substring has a length of 0, or if the
selected bytes cannot be converted to a LARGENT value, then the function returns the
special SQL value NULL. For example:
XATTR_NTEGER('xyz.jim',5,-1,'DECMAL')
String functions
You can use the following string manipulation functions on file names and literal values:
CHAR(expr[, length])
Returns a fixed-length character string representation of its expr argument, where:
expr
can be any data type.
length
if present, must be a literal, integer value.
The resulting type is CHAR or VARCHAR, depending on the function.
The string that CHAR returns is padded with blanks to fill the length of the string. f length is
not specified, it defaults to a value that depends on the type of the argument (expr).
CONCAT(x,y)
Concatenates strings x and y.
HEX(x)
Converts an integer x into hexadecimal format.
Tip: You must enclose strings in single-quotation marks.
You can include a single-quotation mark in a string by using two single-quotation marks.
For example, 'a''b' represents the string a'b.
Appendix A. Policy rule syntax definitions 605
LENGTH(x)
Determines the length of the data type of string x.
LOWER(x)
Converts string x into lower case.
SNAPID(SnapshotName)
Convert a snapshot name to an integer to allow numeric comparisons.
Snapshots are identified by the name that was defined when the snapshot was created.
Logically, snapshots form an ordered sequence of the changes to a file. n other words, a
snapshot that was created on Monday occurred before the snapshot created the next day, on
Tuesday of the same week. The policy language converts snapshot names to unique integer
Ds to allow numeric comparisons. A more recent snapshot has a higher number than an
older snapshot. This allows the rules to determine which files have changed since a given
snapshot was created, and can be used by an incremental backup program to determine
which files have changed since the last backup. For example:
WHERE MODIFICATION_SNAPID > SNAPID(YesterdaysSnapshotForBackup)
SUBSTR(x,y,z)
Extracts a portion of string x, starting at position y, optionally for z characters. f z is not
specified, the extracted portion stops at the end of the string. t is the short form of
SUBSTRNG.
SUBSTRING(x FROM y FOR z)
Extracts a portion of string x, starting at position y, optionally for z characters. f z is not
specified, the extracted portion stops at the end of the string.
UPPER(x)
Converts the string x to upper case.
VARCHAR(expr [, Iength ])
Returns a varying-length character string representation of a character string, date and time
value, or numeric value, where:
expr
can be any data type.
length
if present, must be a literal, integer value.
The resulting type is CHAR or VARCHAR, depending upon the function. Unlike CHAR, the
string that the VARCHAR function returns is not padded with blanks.
606 SONAS mplementation Guide
Numeric functions
You can use numeric calculation functions to place files based on either numeric parts of the
file name, numeric parts of the current date, UNX-client user Ds or group Ds. These can be
used in combination with comparison predicates and mathematical infix operators such as
addition, subtraction, multiplication, division, modulo division, and exponentiation.
INT(x)
Converts number x to a whole number, rounding up fractions of .5 or greater.
INTEGER(x)
Converts number x to a whole number, rounding up fractions of .5 or greater.
MOD(x,y)
Determines the value of x taken modulo y (x % y).
Date and time functions
You can use these date-manipulation and time-manipulation functions to place files based on
when the files are created and the local time of the GPFS node serving the directory where
the file is being created.
CURRENT_DATE
Determines the current date on the GPFS server.
CURRENT_TIMESTAMP
Determines the current date and time on the GPFS server.
DAYOFWEEK(x)
Determines the day of the week from date or timestamp x. The day of a week is from 1 to 7,
where Sunday is 1.
DAYOFYEAR(x)
Determines the day of the year from date x. The day of a year is a number from 1 to 366.
DAY(x)
Determines the day of the month from date or timestamp x.
DAYS(x)
Determines the number of days between date or timestamp x and 0001-01-01.
DAYSINMONTH(x)
Determines the number of days in the month of date x.
DAYSINYEAR(x)
Determines the day of the year of date x.
Appendix A. Policy rule syntax definitions 607
HOUR(x)
Determines the hour of the day of timestamp x. HOUR is a value from 0 to 23.
MINUTE(x)
Determines the minute from timestamp x.
MONTH(x)
Determines the month of the year from date or timestamp x.
QUARTER(x)
Determines the quarter of year from date x. Quarter values are the numbers 1 through 4. For
example, January, February and March are in quarter 1.
SECOND(x)
Returns the seconds portion of timestamp x.
TMESTAMP(sql-numeric-value) or TMESTAMP(sql-character-string-value)
Accepts any numeric value. The numeric value is interpreted as the number of seconds since
January 1, 1970, which is the standard UNX epoch, and is converted to an SQL TMESTAMP
value.
Signed 64-bit LARGENT argument values are supported. Negative argument values cause
TMESTAMP to convert these values to timestamps that represent years before the UNX
epoch.
This function also accepts character strings in the format YYYY-MM-DD HH:MM:SS. A
hyphen (-) or an "at sign () might appear instead of the blank between the date and the
time. The time can be omitted. An omitted time defaults to 00:00:00. f the :SS field is omitted,
it defaults to 00.
WEEK(x)
Determines the week of the year from date x.
YEAR(x)
Determines the year from date or timestamp x.
All of the date and time functions use Universal Time (UT).
608 SONAS mplementation Guide