The DmaContext_t object stores information for DMF in order to provide continuity from one subroutine call to the next. It is an opaque object that is created when a DMF process first loads sitelib.so and it exists until that process unloads it. This context is provided as a parameter for each of the site-defined policy subroutines.

Site-defined subroutines cannot directly access the information held in the context, but they can obtain information from it by using the following subroutines:

Site-defined subroutines can also store their own information in the context and retrieve it on subsequent calls by using the following subroutines:

The DmaFrom_t object specifies the type of policy statement being evaluated.

There are the following possible values:

The DmaIdentity_t object provides information, if known, about the program calling the site-defined subroutine and the user whose request generated the call.

The public member fields and functions of this class are as follows:

---

Note: Any of the descriptive character strings may be set to unknown if the field's true value cannot be determined.

---

The DmaLogLevel_t object specifies the level of a message. The administrator may select a log level in the DMF configuration file; messages with a less severe level than what is specified in the configuration file will not appear in the log.

The DmaRealm_t object specifies the realm. Only the UNIX realm is supported.

The DmaRecallType_t object specifies the type of kernel recall being performed.

The SiteFncMap_t object specifies the site subroutine map. The various DMF processes that can call subroutines in sitelib.so look for a variable named SiteFncMap, of type SiteFncMap_t, in the sitelib.so library. It then uses the addresses provided in this variable to find the site-defined subroutines. If the variable is not found, DMF will not make any calls to subroutines in sitelib.so.

The SiteCreateContext() subroutine provides the opportunity to create a site-specific setup. It is called when sitelib.so is loaded. If no such setup is required, it need not be implemented. If this subroutine returns anything other than DmuNoError, no other subroutines in sitelib.so, including SiteDestroyContext(), will be called by the current process, unless sitelib.so is changed and therefore reloaded.

This subroutine may not issue messages to the user because the user details are unknown at the time it is invoked. If it is invoked by a program with a log file, such as dmfdaemon, it can issue log messages by calling DmaSendLogFmtMessage(). You can call DmaGetContextFlags() to determine if it can issue log messages.

The prototype is as follows:

typedef DmuError_t  (*SiteCreateContext_f)(
        const   DmaContext_t    dmacontext);

The parameter is as follows:

The SiteDestroyContext() subroutine provides the opportunity for site-specific cleanup. It is called when sitelib.so is unloaded. If no such cleanup is required, it need not be implemented. This subroutine may not issue messages to the user because the user details are no longer valid at the time it is invoked. If it is invoked by a program with a log file, such as dmfdaemon, it can issue log messages by calling DmaSendLogFmtMessage(). You can call DmaGetContextFlags() to determine if it can issue log messages.

The prototype is as follows:

typedef void  (*SiteDestroyContext_f)(
        const   DmaContext_t    dmacontext);

The parameter is as follows:

The SiteKernRecall() subroutine allows sites some control over kernel requests to recall a file. It is invoked when DMF receives a kernel request to recall a file. For example, a read() system call for a file that is currently in OFL state would result in SiteKernRecall() being called. The dmget command or the equivalent libdmfusr.so library call would not result in a call to SiteKernRecall().

This subroutine may accept or reject the request or change its priority; no other changes are possible. If the subroutine returns a value other than DmuNoError, the request will be rejected. Changing the priority has no effect at this time.

---

Note: offset and length pertain to the range of the file that the user's I/O request referenced, not the byte range that dmfdaemon will actually recall.

---

The subroutine may not issue messages to the user, but it can issue messages to the DMF daemon log.

The prototype is as follows:

typedef  DmuError_t (*SiteKernRecall_f) (
                DmaContext_t    dmacontext,
        const   DmuFullstat_t   *fullstat,
        const   DmuFhandle_t    *fhandle,
                uint64_t        offset,
                uint64_t        length,
                DmaRecallType_t recall_type,
                DmuPriority_t   *operative_priority);

The parameters are as follows:

The SitePutFile() subroutine allows sites some control over the DMF put requests. It is invoked when a dmput command is issued or when one of the following libdmfusr.so subroutines is called:

This subroutine is not called when automatic space management migrates a file.

---

Caution: If SitePutFile() is implemented, it takes precedence over any when clause being used to control MSP or volume group selection, whether or not SiteWhen() has been implemented.

---

If this subroutine returns a value other than DmuNoError , the put request will be rejected. The subroutine may not issue log messages, but it can issue messages to the user.

The prototype is as follows:

typedef  DmuError_t (*SitePutFile_f) (
        const   DmaContext_t    dmacontext,
        const   DmuFullstat_t   *fstat,
        const   char            *path,
        const   DmuFhandle_t    *fhandle,
        const   int             flags,
        const   DmuVolGroups_t  *policy_volgrps,

        const   DmuPriority_t   user_priority,
        const   int             user_flags,
        const   DmuByteRanges_t *user_byteranges,
        const   DmuVolGroups_t  *user_volgrps,

                DmuPriority_t   *operative_priority,
                int             *operative_flags,
                DmuByteRanges_t *operative_byteranges,
                DmuVolGroups_t  *operative_volgrps);

The parameters are as follows:

The SiteWhen() subroutine provides the opportunity to supply the value for the sitefn variable in when clauses in the following parameters:

This subroutine is not supported in when clauses associated with a DCM cache.

---

Caution: If SitePutFile() is implemented, it takes precedence over any when clause being used to control MSP or volume group selection, whether or not SiteWhen() has been implemented.

---

For example,

SELECT_VG       tp9840  when uid = archive or sitefn = 6

If this subroutine is unavailable, either because it was not implemented or because the sitelib.so library is not accessible, the expression using sitefn is evaluated as being false. Therefore, the example above would be treated as if it were the following:

SELECT_VG       tp9840  when uid = archive or false

Or more simply:

SELECT_VG       tp9840  when uid = archive

If a policy stanza contains multiple references to sitefn , it is possible that the subroutine is only called once and the value returned by that call may be used for several substitutions of sitefn. Therefore, a policy that contains the following will not necessarily call the subroutine three times:

AGE_WEIGHT      -1     0        when sitefn < 10
AGE_WEIGHT      1     .1
SPACE_WEIGHT    1     1e-6      when sitefn != 11
SPACE_WEIGHT    2     1e-9      when sitefn > 19
SPACE_WEIGHT    3.14  1e-12

The subroutine can issue log messages in some circumstances and user messages in others. You can call DmaGetContextFlags() to determine what kind of messages are possible.

The prototype is as follows:

typedef int (*SiteWhen_f) (
        const DmaContext_t  dmacontext,
        const DmuFullstat_t *fstat,
        const DmuFhandle_t  *fhandle,
              DmaFrom_t     fromtyp); 

The parameters are as follows:

The DmaConfigStanzaExists() subroutine checks whether a specified stanza exists in the DMF configuration file.

---

Note: Values in the configuration file may change while DMF is running.

---

The prototype is as follows:

DmaBool_t
DmaConfigStanzaExists(
        const   DmaContext_t    dmacontext,
        const   char            *type,
        const   char            *stanza);

The parameters are as follows:

For example, if the DMF configuration file contained the following:

define  /dmf1
        TYPE            filesystem
        POLICIES        space_policy vg_policy
enddef

Then the following call would return true:

DmaConfigStanzaExists(dmacontext, "filesystem","/dmf1");

The DmaGetConfigBool() subroutine extracts parameter values of type DmaBool_t from the specified stanza in the DMF configuration file. If there is no such parameter definition or if it exists but with a missing or improper value, then the default is used.

---

Note: Values in the configuration file may change while DMF is running.

---

The prototype is as follows:

DmaBool_t
DmaGetConfigBool(
        const   DmaContext_t    dmacontext,
        const   char            *stanza,
        const   char            *param,
                DmaBool_t       default_val);

The parameters are as follows:

The DmaGetConfigFloat() subroutine extracts parameter values of type float from the specified stanza in the DMF configuration file. If there is no such parameter definition or if it exists but with a missing or invalid value, the default is used.

---

Note: Values in the configuration file may change while DMF is running.

---

The prototype is as follows:

float
DmaGetConfigFloat(
        const   DmaContext_t    dmacontext,
        const   char            *stanza,
        const   char            *param,
                float           default_val,
                float           min,
                float           max);

The parameters are as follows:

The DmaGetConfigInt() subroutine extracts parameter values of type int64_t from the specified stanza in the DMF configuration file. If there is no such parameter definition or if it exists but with a missing or invalid value, then a default value is used.

---

Note: Values in the configuration file may change while DMF is running.

---

The prototype is as follows:

int64_t
DmaGetConfigInt(
        const   DmaContext_t    dmacontext,
        const   char            *stanza,
        const   char            *param,
                int64_t         default_val,
                int64_t         min,
                int64_t         max);

The parameters are as follows:

The DmaGetConfigList() subroutine returns a pointer to an array of words found in the parameter in the specified stanza. The items value points to a block of memory containing an array of string pointers are well as the strings themselves; the end of the array is marked by a NULL pointer. The block of memory has been allocated by the malloc() subroutine and can be released with the free() subroutine if desired. The caller is responsible for releasing this memory.

---

Note: Values in the configuration file may change while DMF is running.

---

The prototype is as follows:

DmaBool_t
DmaGetConfigList(
        const   DmaContext_t    dmacontext,
        const   char            *stanza,
        const   char            *param,
                char            *** items);

The parameters are as follows:

The DmaGetConfigStanza() subroutine return a pointer to an array of parameters and values for the specified stanza in the DMF configuration file. (That is, it provides the entire stanza, after comments have been removed.) The items value points to a block of memory containing an array of structures with string pointers as well as the strings themselves; the end of the array is marked by a NULL pointer. The block of memory has been allocated by the malloc() subroutine and can be released with the free() subroutine if desired. The caller is responsible for releasing this memory.

---

Note: Values in the configuration file may change while DMF is running.

---

The prototype is as follows:

DmaBool_t
DmaGetConfigStanza(
        const   DmaContext_t    dmacontext,
        const   char            *stanza,
                DmaConfigData_t **items);

}

The parameters are as follows:

Extracts a string from the specified stanza in the DMF configuration file and returns it. If there is no such parameter definition, the default is used. If the parameter exists but with a missing value, the null string (which is a valid value) is returned.

---

Note: Values in the configuration file may change while DMF is running.

---

The prototype is as follows:

void
DmaGetConfigString(
        const   DmaContext_t    dmacontext,
        const   char            *stanza,
        const   char            *param,
        const   char            *default_val,
        DmuStringImage_t        &result);

The parameters are as follows:

The DmaGetContextFlags() determines if a given subroutine can issue log messages or issue user messages.

---

Note: If DmaFlagContextValid() is not set in the return value, no use should be made of any other bits.

---

DmaGetContextFlags() can return the following values, which may be OR'd together:

The prototype is as follows:

uint64_t
DmaGetContextFlags(
        const   DmaContext_t    dmacontext);

The parameter is as follows:

The DmaGetCookie() subroutine returns the cookie that was stored in dmacontext by a call to DmaSetCookie() . If a NULL value is returned, either the context is invalid or the cookie was not set.

The prototype is as follows:

void *
DmaGetCookie(
        const   DmaContext_t    dmacontext);

The parameter is as follows:

The DmaGetDaemonVolGroups() subroutine returns the volume groups and MSPs that the dmfdaemon is currently configured to use.

---

Note: Values in the configuration file may change while DMF is running.

---

The prototype is as follows:

const DmuVolGroups_t *
DmaGetDaemonVolGroups(
        const   DmaContext_t    dmacontext);

The parameter is as follows:

The DmaGetProgramIdentity() subroutine returns a pointer to the program DmaIdentity_t object in the dmacontext parameter.

---

Note: The program DmaIdentity_t object should not be confused with the user DmaIdentity_t object that is returned by “DmaGetUserIdentity()”. The user identity is usually of much more interest when applying site policies because it defines who is actually making the request as opposed to what process is negotiating the site policies.

---

The prototype is as follows:

const DmaIdentity_t *
DmaGetProgramIdentity(
        const   DmaContext_t    dmacontext);

The parameter is as follows:

The DmaGetUserIdentity() subroutine returns a pointer to the user DmaIdentity_t object in the dmacontext parameter.

The user DmaIdentity_t object contains as much information as could be reliably gathered regarding the identity of the originator of the request. For example, the user identity in the SitePutFile() policy subroutine would identify the process (such as dmput) that made the original DmuPutByPathSync() libdmfusr call.

If DmaGetUserIdentity() is called from within SiteKernRecall(), it will return the identity of dmfdaemon . The identity of the user who initiated the read request that caused SiteKernRecall() to be called is unknown to DMF.

Within SiteCreateContext(), the user details may be as yet unknown; therefore, DmaGetUserIdentity() may return different values than if it is called with the same context from another site-defined policy subroutine. In most cases, the user identity is determined after the call to SiteCreateContext() .

Under certain circumstances, some elements of the DmaIdentity_t structure may be unknown. For example, if a site-defined subroutine is called as a result of a command entered on a client machine running a release prior to DMF 3.1, some elements of the user identity may be unknown.

The prototype is as follows:

const DmaIdentity_t *
DmaGetUserIdentity(
        const   DmaContext_t    dmacontext);

The parameter is as follows:

The DmaOpenByHandle() subroutine opens a file by fhandle , in O_RDONLY mode, and returns the file descriptor.

If there is an error, -1 is returned. It is the caller's responsibility to close the file descriptor.

---

Note: This subroutine is implemented on IRIX only.

---

The prototype is as follows:

int
DmaOpenByHandle(
        const   DmaContext_t    dmacontext,
        const   DmuFhandle_t    *dmuhanp);

The parameters are as follows:

The DmaSendLogFmtMessage() subroutine formats and issues log messages, if log messages are possible. The messages will potentially appear in the calling program's log depending upon the DmaLogLevel_t of the message and the log level selected by the administrator in the DMF configuration file. If log messages are not possible, DmaSendLogFmtMessage() silently discards the message.

The prototype is as follows:

void
DmaSendLogFmtMessage(
        const   DmaContext_t    dmacontext,
                DmaLogLevel_t   log_level,
        const   char            *name,
        const   char            *format,
                ...);

The parameters are as follows:

For example, the following will issue an error message to the calling program's log:

DmaSendLogFmtMessage (dmacontext, DmaLogErr,
               "SiteCreateContext", "sitelib.so problem errno %d",
               errno); 

The DmaSendUserFmtMessage() subroutine formats and sends messages to the user, if user messages are possible. The messages will potentially appear as output from commands such as dmput and dmget, depending upon the severity of the message and the level of message verbosity selected by the user. If user messages are not possible, DmaSendUserFmtMessage() silently discards the message.

The prototype is as follows:

void
DmaSendUserFmtMessage(
        const   DmaContext_t    dmacontext,
                DmuSeverity_t   severity,
        const   char            *position,
                int             err_no,
        const   char            *format,
                ...);

The parameters are as follows:

The DmaSetCookie() subroutine stores a pointer to site-defined subroutine information in dmacontext. This pointer may be retrieved by a call to DmaGetCookie(). The site-defined subroutines are responsible for memory management of the space pointed to by the cookie parameter.

The prototype is as follows:

void
DmaSetCookie(

        const   DmaContext_t    dmacontext,
                void            *cookie);

The parameters are as follows: