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.

The following attribute functions can be used:

GetXattrs(pattern,prototype)

Returns extended attribute key=value pairs of a file for all extended attributes whose keys that match pattern. The key=value pairs are returned in the format specified by prototype.

If the value specified for pattern is '*' or empty then all keys are matched.

The prototype is a character string representing the format of a typical key=value pair. The prototype allows the user to specify which characters will be used to quote values, escape special code points, separate the key and value, and separate each key=value pair.

Some examples of the prototype argument include:

key~n=value^n,       # specify the escape characters
hexkey=hexvalue,     # specify either or both as hexadecimal values
"key\n"="value\n",   # specify quotes on either or both
key:"value^n";       # specify alternatives to = and ,
k:"v^n";             # allow key and value to be abbreviated
key,                 # specify keys only
"value~n";           # specify values only
key='value~n'&       # alternative quoting character
key=value            # do not use a ',' separator; use space instead

You may omit the last or both arguments. The defaults are effectively GetXattrs('*','key^n=hexvalue,').

The GetXattrs function returns an empty string for files that have no extended attributes with keys that match pattern.

The GetXattrs function is supported by the mmapplypolicy command, but it might return NULL in other contexts.

SetBGF(BlockGroupFactor)

Specifies how many file system blocks are laid out sequentially on disk to behave like a single large block. This option only works if --allow-write-affinity is set for the data pool. This applies only to a new data block layout; it does not migrate previously existing data blocks.

SetWAD(WriteAffinityDepth)

Specifies the allocation policy to be used. This option only works if --allow-write-affinity is set for the data pool. This applies only to a new data block layout; it does not migrate previously existing data blocks.

SetWADFG("WadfgValueString")

Indicates the range of nodes (in a shared nothing architecture) where replicas of blocks in the file are to be written. You use this parameter to determine the layout of a file in the cluster so as to optimize the typical access patterns of your applications. This applies only to a new data block layout; it does not migrate previously existing data blocks.

"WadfgValueString" is a semicolon-separated string identifying one or more failure groups in the following format:

FailureGroup1[;FailureGroup2[;FailureGroup3]]

where each FailureGroupx is a comma-separated string identifying the rack (or range of racks), location (or range of locations), and node (or range of nodes) of the failure group in the following format:

Rack1{:Rack2{:...{:Rackx}}},Location1{:Location2{:...{:Locationx}}},ExtLg1{:ExtLg2{:...{:ExtLgx}}}

For example, the following value

1,1,1:2;2,1,1:2;2,0,3:4

means that the first failure group is on rack 1, location 1, extLg 1 or 2; the second failure group is on rack 2, location 1, extLg 1 or 2; and the third failure group is on rack 2, location 0, extLg 3 or 4.

If the end part of a failure group string is missing, it is interpreted as 0. For example, the following are interpreted the same way:

2
2,0
2,0,0

Notes:

Only the end part of a failure group string can be left off. The missing end part may be the third field only, or it may be both the second and third fields; however, if the third field is provided, the second field must also be provided. The first field must always be provided. In other words, every comma must both follow and precede a number; therefore, none of the following are valid:
```
2,0,
2,
,0,0
0,,0
,,0
```
Wildcard characters (*) are supported in these fields.

Here is an example of using setBGF, setWAD, and setWADFG:

RULE 'bgf' SET POOL 'pool1' WHERE NAME LIKE '%' AND setBGF(128) AND setWAD(1) AND setWADFG(1,0,1;2,0,1;3,0,1)

This rule has the same effect as the following command:

mmchattr --block-group-factor 128 --write-affinity-depth 1 --write-affinity-failuregroup "1,0,1;2,0,1;3,0,1"  test

After installing this policy, a newly created file will have the same values for these three extended attributes as it would if mmchattr were used to set them:

(06:29:11) hs22n42:/sncfs # mmlsattr -L test
file name:            test
metadata replication: 3 max 3
data replication:     3 max 3
immutable:            no
appendOnly:           no
flags:
storage pool name:    system
fileset name:         root
snapshot name:
Block group factor:  128                                              -----------------gpfs.BGF
Write affinity depth:  1                                              -----------------gpfs.WAD
Write Affinity Depth Failure Group(FG) Map for copy:1 1,0,1           -----------------gpfs.WADFG
Write Affinity Depth Failure Group(FG) Map for copy:2 2,0,1
Write Affinity Depth Failure Group(FG) Map for copy:3 3,0,1
creation time:        Sat Jun  8 06:28:50 2013
Misc attributes:      ARCHIVE

SetXattr('ExtendedAttributeName', 'ExtendedAttributeValue')

This function sets the value of the specified extended attribute of a file.

Successful evaluation of SetXattr in a policy rule returns the value TRUE and sets the named extended attribute to the specified value for the file that is the subject or object of the rule. This function is effective for policy rules (like MIGRATE and LIST) that are evaluated by mmapplypolicy and for the policy placement rule, SET POOL, when a data file is about to be created.

XATTR(extended-attribute-name [, start [, length]])

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. If the named extended attribute does not exist, XATTR returns the special SQL value NULL.

Note: In SQL, the expression NULL || AnyValue yields NULL. In fact, with a few exceptions, the special SQL value of NULL propagates throughout an SQL expression, to yield NULL. A notable exception is that (expression) IS NULL always yields either TRUE or FALSE, never NULL.

For example, if you wish to display a string like _NULL_ when the value of the extended attribute of a file is NULL you will need to code your policy rules file like this:

define(DISPLAY_NULL,[COALESCE($1,'_NULL_')])
rule external list 'a' exec ''
rule list 'a' SHOW(DISPLAY_NULL(xattr('user.marc')) || ' and ' || DISPLAY_NULL(xattr('user.eric')))

Here is an example execution, where either or both of the values of the two named extended attributes may be NULL:

mmapplypolicy /gig/sill -P /ghome/makaplan/policies/display-null.policy -I test -L 2
   ...
WEIGHT(inf) LIST 'a' /gg/sll/cc SHOW(_NULL_ and _NULL_)
WEIGHT(inf) LIST 'a' /gg/sll/mm SHOW(yes-marc and _NULL_)
WEIGHT(inf) LIST 'a' /gg/sll/bb SHOW(_NULL_ and yes-eric)
WEIGHT(inf) LIST 'a' /gg/sll/tt SHOW(yes-marc and yes-eric)

GPFS/Policy/SQL is a subset of standard ISO/ANSI SQL, with additional extensions and modifications to facilitate GPFS/ILM. Regarding the NULL value, GPFS/Policy/SQL supports the unknown value meaning of NULL.

start

Is the optional starting position within the extended attribute value. The default is 1.

length

Is 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.

Note: XATTR (name,i,k) == SUBSTR(XATTR(name),i,k).

Some extended attribute values represent numbers or timestamps as decimal or binary strings. Use the TIMESTAMP, XATTR_FLOAT, or XATTR_INTEGER 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:

extended-attribute-name

Specifies any SQL expression that evaluates to a character string value. If the named extended attribute does not exist, XATTR returns the special SQL value NULL.

start

Is the optional starting position within the extended attribute value. The default is 1.

length

Is 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:

BIG_ENDIAN_DOUBLE or BD - a signed binary representation, IEEE floating, sign + 11 bit exponent + fraction. This is the default when executing on a "big endian" host OS, such as AIX® on PowerPC®.
BIG_ENDIAN_SINGLE or BS - IEEE floating, sign + 8-bit exponent + fraction.
LITTLE_ENDIAN_DOUBLE or LD - bytewise reversed binary representation. This is the default when executing on a "little endian" host OS, such as Linux® on Intel x86.
LITTLE_ENDIAN_SINGLE or LS - bytewise-reversed binary representation.
DECIMAL - 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 LITTLE_ENDIAN_DOUBLE.
If the extended attribute does not exist, the selected substring has a length of 0, or the selected bytes cannot be converted to a floating-point value, the function returns the special SQL value NULL.

XATTR_INTEGER(extended-attribute-name [, start [, length, [, conversion_option]]])

Returns the value of (a substring of) the extended attribute named by its argument, converted to a SQL LARGEINT value, where:

extended-attribute-name

Specifies any SQL expression that evaluates to a character string value. If the named extended attribute does not exist, XATTR returns the special SQL value NULL.

start

Is the optional starting position within the extended attribute value. The default is 1.

length

conversion_option

Specifies how the bytes are to be converted to a LARGEINT value. Supported options include:

BIG_ENDIAN - a signed binary representation, most significant byte first. This is the default when executing on a "big endian" host OS, such as AIX on PowerPC.
LITTLE_ENDIAN - bytewise reversed binary representation. This is the default when executing on a "little endian" host OS, such as Linux on Intel x86.
DECIMAL - 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 (B, L, or D, for example).
If the extended attribute does not exist, the selected substring has a length of 0, or the selected bytes cannot be converted to a LARGEINT value, the function returns the special SQL value NULL. For example:
```
XATTR_INTEGER('xyz.jim',5,-1,'DECIMAL')
```