IBM General Parallel File System for AIX: Data Management API Guide

Semantic changes to DMAPI functions

Following is a description of changes in the semantics of DMAPI functions in GPFS. These changes are entailed mostly by the multi-node environment. For a list of additional error codes that are used in the GPFS implementation of DMAPI, see "Additional error codes returned by DMAPI functions". For C declarations of all DMAPI functions in the GPFS implementation of DMAPI, see Appendix B, "DMAPI functions in GPFS".

• The following DMAPI functions can be invoked on any node, not just the session node, as long as the session exists on some node in the GPFS nodeset.
  • dm_getall_disp
  • dm_query_session
  • dm_send_msg
• DMAPI functions that reference a file system, as opposed to an individual file, can be made on any node, not just the session node. Being able to call certain functions on any node has advantages. The DM application can establish event monitoring when receiving a mount event from any node. Also, a distributed DM application can change event lists and dispositions of any file system from any node.
  • dm_set_eventlist
  • dm_get_eventlist
  • dm_set_disp
  • dm_get_mount_info
  • dm_set_return_on_destroy
  • dm_get_bulkattr
  • dm_get_bulkall
• The following functions, that construct a handle from its components, do not check if the resulting handle references a valid file. Validity is checked when the handle is presented in function calls that actually reference the file.
  • dm_make_handle
  • dm_make_fshandle
• The following functions that extract components of the handle, do not check whether the specified handle references a valid file. Validity is checked when the handle is presented in function calls that actually reference the file.
  • dm_handle_to_fsid
  • dm_handle_to_ino
  • dm_handle_to_igen
• dm_handle_to_fshandle converts a file handle to a file system handle without checking the validity of either handle.
• dm_handle_is_valid does not check if the handle references a valid file. It verifies only that the internal format of the handle is correct.
• dm_init_attrloc ignores all of its arguments, except the output argument locp. In the GPFS implementation of DMAPI, the location pointer is initialized to a constant. Validation of the session, token, and handle arguments is done by the bulk access functions.
• When dm_query_session is called on a node other than the session node, it returns only the first eight bytes of the session information string.
• dm_create_session can be used to move an existing session to another node, if the current session node has failed. The call must be made on the new session node. See Chapter 5, "Failure and recovery of Data Management API for GPFS" for details on session node failure and recovery.
• Assuming an existing session using dm_create_session does not change the session id. If the argument sessinfop is NULL, the session information string is not changed.
• The argument maxevent in the functions dm_set_disp and dm_set_eventlist is ignored. In GPFS the set of events is implemented as a bit-map, containing a bit for each possible event.
• The value pointed to by the argument nelemp, on return from the functions dm_get_eventlist and dm_get_config_events, is always DM_EVENT_MAX-1. The argument nelem in these functions is ignored.
• The field dt_nevents in the structure dm_stat_t, returned by the functions dm_get_fileattr and dm_get_bulkall, always has the value DM_EVENT_MAX-1.
• The functions dm_get_config and dm_get_config_events ignore the arguments hanp and hlen. This is because the configuration is not dependent on the specific file or file system.
• The function dm_set_disp, when called with the global handle, ignores any events in the event set being presented, except the mount event. When dm_set_disp is called with a file system handle, it ignores the mount event.
• The function dm_handle_hash, when called with an individual file handle, returns the i-node number of the file. When dm_handle_hash is called with a file system handle, it returns the value 0.
• The function dm_get_mountinfo returns two additional flags in the me_mode field in the dm_mount_event structure. The flags are DM_MOUNT_LOCAL and DM_MOUNT_REMOTE. See "Mount and unmount" for details.