Semantic changes to DMAPI functions

For a list of additional error codes that are used in DMAPI for GPFS, see Additional error codes returned by DMAPI functions. For C declarations of all the DMAPI for GPFS functions, refer to the dmapi.h file located in the /usr/lpp/mmfs/include directory.

• 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 cluster.
  • 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
  • dm_make_xhandle
• The following data movement functions may be invoked on any node within the GPFS cluster, provided they are run as root and present a session ID for an established session on the session node. For guidelines on how to perform data movement from multiple nodes, see Parallelism in Data Management applications.
  • dm_read_invis
  • dm_write_invis
  • dm_probe_hole
  • dm_punch_hole
• 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_igen
  • dm_handle_to_ino
  • dm_handle_to_snap
• 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 DMAPI for GPFS, 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 Failure and recovery of IBM Storage Scale 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 bitmap, 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 dt_nevents field in the dm_stat_t structure, which is returned by the dm_get_fileattr and dm_get_bulkall functions, has a value of DM_EVENT_MAX-1 when the file has a file-system–wide event enabled by calling the dm_set_eventlist function. The value will always be 3 when there is no file-system–wide event enabled. A value of 3 indicates that there could be a managed region enabled for the specific file, which might have enabled a maximum of three events: READ, WRITE, and TRUNCATE.
• 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 inode 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.