The MLI Application Programming Interface

Overview of MLI Calls

Note that the calls umaCreate(), umaReconnect() and umaGetMsg() are the only MLI calls that exhibit blocking behavior until they either complete or time out.

MLI Call Parameters

attrpairs

In umaSetAttr() and umaGetAttr(), a set of name-value pairs terminated by NULL, specifying (changeable) session attributes. The names are specified by quoted strings. Currently, these names include:

ETIME

Specifies the ending time of data reporting, that is, times greater than ETIME are not reported. [UMATimeSec]

INTERVAL

Specifies the session data reporting interval in seconds. [UMATimeSec]

HISTORY_ONLY

Indicates that only historical data is requested either from UMADS or from a specified input file. [UMABoolean] Setting this attribute TRUE may cause the session's current time pointer to be repositioned to an earlier time and may make times later than those in UMADS or the specified file unreachable (unless reset). Setting this attribute to TRUE will automatically set the attribute RECENT_ONLY to FALSE.

The default value for HISTORY_ONLY depends on the session source as described in the manual page of the umaSetAttr() MLI call.

PARTIAL

When regular interval collection times are in effect, setting PARTIAL to TRUE indicates that a requested change of interval size can take place at the next regular collection time for the shorter of the new and old intervals [UMABoolean]. Otherwise, the change would take place at the time that the old interval and new interval start times occur together. Therefore, this specification may result in either a single truncated (partial) old or new interval at the time the change is made, depending on whether the new interval is shorter or longer than the old. The default value of PARTIAL is FALSE.

Note that this specification has no meaning when regular interval collection times are not in effect.

RECENT_ONLY

Indicates that only data from the Recent Data Facility is requested from UMA, that is, private file or UMADS data are excluded. [UMABoolean] It is an error to attempt to set this attribute to TRUE when either a private file or UMADS have been designated as the source. Setting this attribute to TRUE may cause the session's current time pointer to be repositioned and it may make times prior to those in the Recent Data Facility unreachable (unless reset). Setting this attribute to TRUE will automatically set the attribute HISTORY_ONLY to FALSE. The default value for RECENT_ONLY depends on the session source as described in the manual page of the umaSetAttr() MLI call.

PRIO

A non-negative integer specifying the session attribute: relative priority of data message delivery to the MAP. [UMAPrio] Increasing values designate decreasing priority. The default value of PRIO is 3. The highest priority is for PRIO equal to zero.

STIME

Specifies the starting time of data collection. Times equal to or greater than STIME are reported subject to their being less than or equal to ETIME. [UMATimeSec]

channel_flag

In umaGetMsg(), specifies whether umaGetMsg() should return only in-band messages (UMA_IN_BAND_ONLY), only out-of-band messages (UMA_OUT_OF_BAND_ONLY) or either in-band or out-of-band messages (UMA_ANY_BAND). When only out-of-band messages are to be delivered, in-band messages are held until a call is made to umaGetMsg() with the channel_flag set to either UMA_ANY_BAND or UMA_IN_BAND_ONLY. Similarly, when only in-band messages are requested, out-of-band messages are held until a call is made with the channel_flag set to either UMA_ANY_BAND or UMA_OUT_OF_BAND_ONLY.

dclass

specifies a message class. [UMAClass]

dsubcls

specifies a message subclass. [UMASubClass]

dbid

In umaCreate(), specifies the data base id in UMADS. [<string>].

destination

In umaCreate() specifies the MAP itself, an output file or UMADS as a destination for reporting. See the umaCreate() call manual page for a complete description of values. [<string>]

flushflags

In umaStop(), contains the flags that indicate which previously issued umaStart() requests are cancelled. [UMAFlushFlags] The possible values of flushflags are:

UMA_HELD

Cancel only those requests that have been started but not released.

UMA_RELEASED

Cancel only those start requests that have been released.

UMA_ALLSTARTED

Cancel both held and released requests.

location

In umaCreate(), qualifies source and destination with a specification similar to that defined for sysid, that is, a qualified node name (e.g. srv.accting.acme.com), or as an IP address in string form with periods (e.g. 129.210.1.1). [<string>]

position

In umaSeek(), a relative position measured in intervals from a specified time. [UMAInt4]

provider

In umaRequestConfig(), umaSetThreshold(), umaStart() and umaStop(), designates the registered provider for which collection classes and subclasses are specified. [UMAProvider] The defined constant <OS>_DATAPOOL is used to designate the classes and subclasses defined by an operating system-specific datapool¹.

reason

A reason code for a UMA error indication in umaCreate(), umaReconnect(), and umaGetReason(). [UMAReasonCode]

segflags

In umaStart(), these are flags that specify the segment types to be reported. [UMASegFlags] The segment types defined in the Data Pool Definitions (see reference DPD) currently include:

1. UMA_ASEG, indicating that all available segment types are to be reported.

2. UMA_BSEG, indicating universally supplied data.

3. UMA_OSEG, indicating optional data defined in the standard.

4. UMA_ESEG, indicating vendor-specific data.

sessid

Specifies a session identifier. [UMASessId]

sess_req

In umaGetMsg() specifies a requested session. [UMASessId]

sess_ret

A returned session identifier in umaGetMsg(). [UMASessId]

source

In umaCreate(), specifies the source(s) of data for reporting to be current collections from UMA data providers, an input file, or UMADS. [<string>]

sprops

In umaCreate(), contains the session property flags. [UMAProp] Session property flags are set, reset, cleared, and tested with the macro operators UMA_SET, UMA_RESET, UMA_CLEAR, and UMA_ISSET, respectively. All property flags are initially in a reset state. Currently, these properties include:

1. A property UMA_COHERENT for an MLI requester session to specify that it requires that subclass coherency criteria be applied to collections.

2. A session property flag UMA_NOTERM to allow all reporting associated with the session to continue if the session is closed. This allows a collection and reporting activity to continue in a background mode.

3. A session property flag UMA_NOTREGULAR for a session to request exemption from common, regularised interval data reporting.

4. A property flag UMA_SYNCH for a requester session to specify that it requires time synchronisation between different UMA data providers.

subclass

In umaStart(), specifies the UMA subclass to be reported. [UMASubClass]

sysid

In umaCreate() and umaReconnect(), specifies the node from which data is to be collected. May be specified as a qualified node name (for example srv.payroll.acme.com) or as an IP address in string form with periods (for example 129.210.1.1). [<string>]

timeout

In umaGetMsg(), specifies a time in seconds and microseconds to wait for a message to be available before returning. In umaCreate() and umaReconnect(), specifies a time in seconds and microseconds to wait for communication and establishing or re-establishing a session. The time used is the sum of timeout.tv_sec seconds plus timeout.tv_usec microseconds. [UMATimeVal]

tstamp

In umaSeek(), defines a time stamp in seconds, for UMA data interval searches. [UMATimeStamp]

whence

In umaSeek, specifies whether the seek is relative to UMA_CTIME, UMA_LTIME, UMA_STIME or to a timestamp.

UMAWorkInfo

In umaRequestConfig(), the composite of a set of UMAWorkDescr structures returned in the metadata class "Configuration", subclass "WorkInfo Attributes". UMAWorkInfo defines the work unit tags that a provider may use to link a specific instance of metric subclass collection with a logical workload. UMAWorkInfo tags are global for a provider. See the umaRequestConfig() MLI call for details.

UMAWorkDefn

In umaStart() and umaStop(), a structure used to specify reporting filters by use of UMAWorkInfo items, instances, and granularity of reporting. See the umaStart() MLI call for details.

MLI Macro Operators

 

UMA_SET(FIELD, FLAG)          /* set FLAG in FIELD        */
UMA_RESET(FIELD, FLAG)        /* reset FLAG in FIELD      */
UMA_ISSET(FIELD, FLAG)        /* test IN FIELD            */
UMA_CLEAR(FIELD)              /* clear all flags in FIELD */
UMA_SESSIONEXISTS(sessid)     /* test session existence   */

Note that a flag field must first be cleared (using UMA_CLEAR) before it is first used.

The macro operator definitions are established by including the <uma.h> header file.

UMA MLI Call Descriptions

Each call is described by a model definition that includes the returned type, the function name, and its formal parameters. This is followed by a specification of the formal parameter types as expected by the MLI and a description of the interface behaviour. A list of UMA status and reason codes applicable to the call concludes the call description (definitions of these codes are included with the UMA type definitions for UMAStatusCode and UMAReasonCode, respectively).

NAME

umaClose - Shut down one or all active sessions of a MAP.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaClose(
UMASessId sessid /* in */
UMAReasonCode *reason /* out */
);

DESCRIPTION

The function umaClose() shuts down the session denoted by sessid. Data will continue to be collected and reported to the session's destination (until the session's end time is reached) if the UMA_NOTERM property flag was set when the session was created (see tagmref_umaCreate .

DIAGNOSTICS

The returned value of umaClose() indicates the general outcome (status code). Status and reason codes that apply to umaClose() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	-
UMS_COMM	UMR_SEND	Communications error when sending messages to UMA facility
UMS_SESSID	-	Invalid sessid specified
UMS_SESSION	UMR_RESOURCE	Resource not available

NAME

umaCreate - Establish a new session for a MAP.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaCreate(
    char            *destination,      /* in  */
    char            *sysid,            /* in  */
    char            *source,           /* in  */
    UMAProp         sprops,            /* in  */
    UMASessId       *sessid,           /* out */
    UMATimeVal      *timeout           /* in  */
    UMAReasonCode   *reason            /* out */
);

DESCRIPTION

The source designator may be any of:

"RECENT" /* recent data only */
"[<location>:]UMADS[(dbid)]" /* UMADS data only */
"[<location>:]UMADS[(dbid)] + RECENT" /* UMADS and recent data */
"UMA_SFILE" /* environment-specified file */
"[<location>:]<path>[(import)]" /* private file */

The destination designator may be any of:

"[<location>:]UMADS[(dbid)]" /* UMADS data only */
"UMA_DFILE" /* environment-specified file */
"[<location>:]<path>[(export)]" /* private file */
UMA_MAP /* defined macro MAP destination */

The function umaCreate() requests the UMA facility to open a session with the specified source (source of the performance data) and destination (where the data is to be reported). The session properties are indicated by sprops. The returned parameter sessid is subsequently used by the calling MAP to communicate with UMA over this session.

If a connection to sysid and a session are not established within timeout.tv_sec seconds plus timeout.tv_usec microseconds, umaCreate() will return with a status code of UMS_COMM and reason code UMR_TIMEOUT.

<location> identifies a specific UMADS or file physical location. It overrides the presumed location established by UMA administration. If unspecified, the default source location is the presumed location for sysid. The default destination location is that in effect for source. <location> is specified either as a qualified node name (e.g. server.accting.acme.com), or as an IP address in string form with periods (e.g. 129.210.1.1).

The data reported is for the node designated by sysid. The string "UMA_LOCAL" designates the node that is executing the Data Services Layer (DSL) accessed by this MAP.

Note that sysid is the system for which the data is reported; it is not necessarily the system on which data resides.

To specify reporting of current collections from UMA data providers and UMADS in a seamless fashion, a string of the form "UMADS + RECENT" is used for source. (In this context "UMADS" is an abbreviation for "[<location>:]UMADS[(dbid)]".) To restrict the source to the current collections (i.e. to the contents of the Recent Data Facility), the string "RECENT" is used. To restrict the source to UMADS only, a string of the form "UMADS" is used.

In addition, data may be read from a private file as follows:

1. If source is the string "UMA_SFILE", the MAP's environment is searched for a string "UMA_SFILE=[<location>:]<path>[(import)]";

   otherwise

2. source contains a direct specification of the form [<location>:]<path>[(import)].

If destination is "UMA_MAP" then the data collected will be queued for reading by the issuing session. If the destination is not "UMA_MAP" or "UMADS", the data will be written to the file specified by destination as follows:

1. if destination is the string "UMA_DFILE", the MAP's environment is searched for a string of the form "UMA_DFILE=[<location>:]<path>[(export)]";

   otherwise

2. destination contains a direct specification of the form [<location>:]<path>[(export)].

Note that when the destination is "UMADS" and the source is not "UMADS", the only source permitted is the Recent Data Facility; that is, source must be "RECENT" or it may be "UMADS + RECENT" with the RECENT_ONLY attribute set to TRUE.

If the source and destination are two different UMADS areas (i.e. for different sysids or different dbids), the following additional characteristics apply to interval sizes:

1. If an interval in the source UMADS area is equal to or greater than the specified session interval, the destination interval actually written will be a copy of the source UMADS interval;

   otherwise

2. intervals from the source UMADS area are aggregated until the time that is a multiple of the requested destination interval is reached or exceeded.

In addition, if the destination UMADS area already exists, the first interval actually written will be one that strictly follows the last one existing in the destination. That is, data will only be appended and not overwritten or merged.

Data from a file source may only be written to a not-previously-existing UMADS area. Data written to a private file destination can only be written to a not-previously-existing file, that is, file destinations cannot be appended.

Private files are normally written so that they may be read by the UMA implementation that created the file. If, however, it is desired to write such a file in UMA message format so that it may be read by any UMA implementation, the "(export)" suffix is added to the file path following the file name as in /home/uma/daily(export). As a source, the "(import)" suffix is added instead. Export private files are written in Canonical A message format and include all necessary metadata.

Also note that sources or destinations that are specified by a simple file name will be searched for in or written to the MAP's current working directory.

If permissions allow the user and the MAP to create a session, and if the session can be successfully established, the argument sessid is set to the session identifier and the call returns a status of UMS_SUCCESS.

SESSION

A session may be opened by a MAP purely for the setup of data reporting directed to a named destination (that is, a destination other than the MAP itself). In this case, once the setup is complete, the invoking MAP may no longer be needed and the session may then be shut down. Reporting to the specified destination can be made to continue by setting the session property UMA_NOTERM. It is not valid to specify UMA_NOTERM when the destination is a MAP. If, after shutting down a session with the UMA_NOTERM property, it is necessary to resume control of the reporting, a umaReconnect() call may be issued for the same destination named in the session that originated the reporting.

UMA will not normally attempt to schedule data collections from different UMA Data Capture Layer instances (that is, Data Capture Layers on different hosts) so that they occur at the same point in time, that is they will not necessarily be synchronised). Setting the session property UMA_SYNCH indicates that for this session, global collector synchronisation is requested.

UMA permits the application of collection atomicity criteria to ensure that the data collected within UMA subclasses are coherent. (If the criteria are not met, UMA will attempt to repeat the collection). Setting the session property UMA_COHERENT indicates that for this session, data coherency criteria are to be applied if they exist. Coherency criteria are specified as a time window value for allowable skew and a retry count in the configuration file for the UMA instance.

The session property UMA_NOTREGULAR can be set to exempt a session from the enforced use of regular intervals. The maximum interval is equivalent to 24 hours in any case. See the discussion for the MLI function call umaSetAttr() for more details about intervals.

DIAGNOSTICS

The returned values of umaCreate() indicate the outcome of the call (status code) and the reason for a failed status (reason code). If the call is not successful, the returned value of sessid will not be defined. Status and reason codes that apply to umaCreate() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_COMM	UMR_CONNECT	Attempt to connect to UMA failed
	UMR_NETWORK	Network error
	UMR_RECEIVE	Communications error when receiving messages from UMA
	UMR_RESOURCE	Insufficient system resources
	UMR_SEND	Communications error when sending messages to UMA
	UMR_SYSERR	System error while communicating with UMA
	UMR_TIMEOUT	Timeout while attempting to connect to UMA
UMS_DEST	UMR_ACTIVE	This destination is currently the target of another session
	UMR_CONFLICT	Conflict between source and destination
	UMR_UNKNOWN	Specified destination unknown
UMS_PROPERTY	UMR_CONFLICT	Conflict between property and destination
	UMR_INVALID	Property invalid
UMS_PROTOCOL	UMR_HEADER	Control message header not recognised by UMA Data Services
	UMR_MESSAGE	Control message content not recognised by UMA Data Services
UMS_SESSION	UMR_MAX	Maximum resources exceeded for this MAP
	UMR_PERMISSION	Access denied
	UMR_RESOURCE	Resource not available
	UMR_SYSERR	System error while establishing session
	UMR_UMADS	UMADS error while establishing session
UMS_SOURCE	UMR_UNKNOWN	Specified source unidentified

NAME

umaGetAttr - Obtain a session's attributes.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaGetAttr(
UMASessId sessid, /* in */
... /* in/out */
);

DESCRIPTION

umaGetAttr() returns the session attributes for the session denoted by sessid.

The sessid parameter is followed by a null-terminated variable length list of name variable pairs (attrpairs), each pair consisting of a quoted attribute name followed by a comma and the attribute variable. Attributes for the names specified in this list are returned to their corresponding variables. See the description of the umaSetAttr call and MLI Call Parameters for details on syntax and available session attributes. The variable length argument list must be terminated by a NULL argument.

EXAMPLE

This example assumes that there is an active session with sessid sessid1.

#include <uma.h>

UMAStatusCode status;
UMASessId sessid1;
UMATimeSec stime;
UMATimeSec intval;

status=umaGetAttr(sessid1, "STIME", &stime, "INTERVAL",
&intval, (char*)NULL);

DIAGNOSTICS

The returned value of umaGetAttr() indicates the general outcome (status code). Supplementary reason code for a failed status can be obtained by calling the umaGetReason() function. Status and reason codes that apply to umaGetAttr() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_ATTR	UMR_INVALID	An invalid attribute name specified
UMS_EOS	-	End of session encountered
UMS_SESSID	-	Invalid session specified

NAME

umaGetMsg - Return a pointer to the next available data or control message.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaGetMsg(
UMASessId sess_req, /* in */
UMAChannelFlags channel_flag, /* in */
UMASessId *sess_ret, /* out */
char **msg_ptr, /* out */
UMATimeVal *timeout /* in */
);

DESCRIPTION

The umaGetMsg() call is used to access data and control messages for a session. It sets the pointer msg_ptr to the next available message for the session indicated by sess_ret. The message will either be a data message or a control status message. The setting of channel_flag determines whether messages are to be selected from the in-band queue only (UMA_IN_BAND_ONLY), the out-of-band queue only (UMA_OUT_OF_BAND_ONLY), or from any band (UMA_ANY_BAND).

If there are no queued messages for this session, umaGetMsg() will wait at most timeout.tv_sec seconds plus timeout.tv_usec microseconds for a message to appear. If the numeric value of both fields is zero, the return is immediate whether there is a message queued or not (if a message is queued, it will be returned). If the pointer argument timeout is the null pointer, the call blocks until either a message has been queued, or until an interrupt signal (SIGINT) is received by the caller, in which case no message is returned and the status code is set to the defined value UMS_SIGNAL and the reason code to UMR_INTR. In any event, an interrupt signal will always result in an immediate return with this status and reason code.

If no message is queued and no error has occurred (within the time specified by timeout), the function returns the defined status value UMS_NOMSG. In this case, the function umaGetReason() will return the reason code UMR_TIMEOUT.

sess_req identifies the session requested. If the defined value UMA_ANYSESSION is specified for sess_req, then, if a message is returned, it will be from the highest priority session having messages queued. If the call fails or is interrupted, the reason code obtained via the function umaGetReason() for any existing session will indicate the condition.

In any case, sess_ret will be set to the sessid for the session message actually returned. If no message is returned, sess_ret is set to UMA_NULLSESSION.

When a session end time is reached, umaGetMsg() will return an end of session condition message (UMA_EOS). A session whose destination is a file or UMADS will be automatically closed when this end time is reached.

When end-of-file is detected on the source for a session whose source is UMADS or a file, uma_GetMsg() will return an end-of-file condition message (UMA_EOF). A session whose destination is a file or UMADS will be automatically closed when this end-of-file condition is encountered.

If any of the required session attributes STIME, ETIME, or INTERVAL have not been set, umaGetMsg() will return a NULL message pointer (msg_ptr). In this case, the returned status code will be set to UMS_ATTR with reason code UMR_INCOMPLETE.

---

DIAGNOSTICS

The returned value of umaGetMsg() indicates the general outcome (status code). Supplementary reason code for a failed status can be obtained by calling the umaGetReason() function. Status and reason codes that apply to umaGetMsg() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_ATTR	UMR_INCOMPLETE	Required attribute not specified
UMS_COMM	UMR_RECEIVE	Communications error when receiving messages from UMA
	UMR_SEND	Communications error when sending messages to UMA
	UMR_SYSERR	System error while communicating with UMA
UMS_NOMSG	UMR_TIMEOUT	Timeout occurred, no message is returned
UMS_SESSID	-	Invalid sessid specified
UMS_SESSION	UMR_RESOURCE	Insufficient system resources
UMS_SIGNAL	UMR_SYSERR	System error while setting signal handler
	UMR_INTR	Interrupt signal (SIGINT) caught
UMS_TIME	UMR_INVALID	Invalid timeout value specified

NAME

umaGetReason - Return the reason and status codes pertaining to an established session.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaGetReason(
UMASessId sessid, /* in */
UMAStatusCode *status, /* out */
UMAReasonCode *reason /* out */
);

DESCRIPTION

The function umaGetReason() returns a reason code (along with the status code for an established session (denoted by sessid). The reason code returned by umaGetReason() is for the most recent preceding MLI call for that session.

NOTE

umaCreate() and umaReconnect() functions return reasons through their parameter lists.

DIAGNOSTICS

Status and reason codes that apply to umaGetReason() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_SESSID	-	Invalid sessid

NAME

umaReconnect - Re-establish the connection to a previously closed session.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaReconnect(
char *destination, /* in */
char *sysid, /* in */
UMASessId *sessid, /* out */
UMATimeVal *timeout /* in */
UMAReasonCode *reason /* out */
);

DESCRIPTION

umaReconnect() requests the re-establishment of control between the calling MAP and the specified destination on the specified sysid. The specified destination must be either "UMADS" or a private file and it must be currently active, that is, being reported to. The session that originally specified the reporting must have been created with the UMA_NOTERM property, and must no longer exist at the time of the umaReconnect() call. The new session, denoted by sessid, will have the same attributes and properties as the session previously active for this same destination.

If a connection to sysid and a session are not established within timeout.tv_sec seconds plus timeout.tv_usec microseconds, umaReconnect() will return with a status code UMS_COMM and reason code UMR_TIMEOUT.

The destination designator may be any of:

"[<location>:]UMADS[(dbid)]" /* UMADS data only */
"UMA_DFILE" /* environment-specified file */
"[<location>:]<path>" /* private file */

<location> identifies a specific UMADS or file location. It overrides the presumed location established by UMA administration.

The semantics of sysid in umaReconnect() are the same as for the umaCreate() call.

---

DIAGNOSTICS

The returned value of umaReconnect() indicates the general outcome (status code). The supplementary reason code for a failed status is returned as an argument to the function. Status and reason codes that apply to umaReconnect() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_COMM	UMR_CONNECT	Attempt to connect to UMA failed
	UMR_NETWORK	Network error
	UMR_RECEIVE	Communications error when receiving messages from UMA
	UMR_RESOURCE	Insufficient system resources
	UMR_SEND	Communications error when sending messages to UMA
	UMR_SYSERR	System error while communicating with UMA
	UMR_TIMEOUT	Timeout while attempting to connect to UMA
UMS_DEST	UMR_ACTIVE	This destination is currently the target of another session
	UMR_INVALID	Specified destination invalid
UMS_PROTOCOL	UMR_HEADER	Control message header not recognised by UMA Data Services
	UMR_MESSAGE	Control message content not recognised by UMA Data Services
UMS_SESSION	UMR_MAX	Maximum resources exceeded for this MAP
	UMR_PERMISSION	Access denied
	UMR_RESOURCE	Resource not available
	UMR_SYSERR	System error while establishing the session
	UMR_UMADS	UMADS error while establishing the session

NAME

umaRelease - coordinate and start or stop reporting the requested classes and subclasses or activate threshold settings.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaRelease(
UMASessId sessid /* in */
);

DESCRIPTION

umaRelease() informs the UMA facility to execute any assembled requests from previous umaStart(), umaStop() and umaSetThreshold() calls for the indicated session(s). The parameter sessid may be assigned the defined symbol UMA_ALLSESSIONS to indicate that any such assembled requests MAP should be released and executed.

NOTE

umaRelease() will take effect only when all the required session attributes STIME, ETIME, and INTERVAL have been set.

DIAGNOSTICS

The returned value of umaRelease() indicates the general outcome (status code). Supplementary reason code for a failed status can be obtained by calling the umaGetReason() function. Status and reason codes that apply to umaRelease() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_COMM	UMR_SEND	Communications error while sending messages to UMA (one or more sessions)
UMS_SESSID	-	Invalid session specified
UMS_SESSION	UMR_RESOURCE	Insufficient resource (one or more sessions)

NAME

umaRequestConfig - request the reporting of system and UMA configuration information to a MAP.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaRequestConfig(
UMASessId sessid, /* in */
UMAProvider provider, /* in */
UMAClass dclass, /* in */
UMASubClass dsubcls /* in */
);

DESCRIPTION

The function umaRequestConfig() requests the reporting of configuration data as specified by provider, dclass and dsubcls for the session specified by sessid. The defined symbols UMA_ALLCLASSES and UMA_ALLSUBCLASSES may be used for dclass or dsubcls respectively, to indicate that all classes and subclasses are to be selected.

STRUCTURES AND METADATA

The following terminology will be used in this discussion:

Instantiated

MLI subclasses are equivalent to DCI classes that contain metric items. Such DCI subclasses will be designated "instantiated subclasses". Instantiated subclasses may not contain other classes.

Built-in

The MLI supports static classes and subclasses that are defined to user applications by the inclusion of header files of predefined structures for the subclasses. Messages in these built-in classes and subclasses are available the "Canonical C" form of UMA UDUs and do not require metadata for interpretation. Metadata may, however, be optionally supplied in the form of "Class Attributes" and "Subclass Attributes" subclass messages in the "UMA Configuration Class"

Dynamic

Dynamic classes and subclasses are those that a provider explicitly registers, typically with the UMA DCI. These classes and subclasses may come and go during the course of a provider instantiation and require that metadata provided by the "Subclass Attribute" subclass messages in the "UMA Configuration Class" be used to interpret them. Messages in dynamic classes and subclasses are made available in the "Canonical A" form of MLI UDUs. Built-in classes may not have dynamic subclasses.

The subclass "Implementation" of class "UMA Configuration" contains a class-type array. In addition to implementation status, this array contains two bit flags, UMA_BUILTIN and UMA_DYNAMIC. UMA_BUILTIN will be set if the class is available as a built-in class, UMA_DYNAMIC will be set if the class has been dynamically registered by its provider. If a class-type has UMA_DYNAMIC set then metadata in a "Subclass Attributes" subclass of class "UMA Configuration" will always be available to describe its subclasses.

In the case when both built-in and dynamic forms of a subclass are defined, the MAP may select which is to be delivered by setting the UMA_WORKLOAD_DYNAMIC flag in the umaStart() call. The MLI service layer will then construct UDU messages according to whichever form has been selected.

Class

Data Pool classes and subclasses are manipulated by MAPs (MLI consumers) using class and subclass handles (of types UMAClass and UMASubClass). The handles have static values for built-in classes and subclasses. For dynamic classes and subclasses, the class and subclass handles are dynamically assigned by the MLI service functions (the local UMA Data Services Layer serving the requesting MAP). A common DSL service to all local MAPs provides consistent handle values to all its local MAPs for the duration of the DSL's existence.

An MLI subclass handle is identical to the DPD (or DCI) class identifier of the deepest class in the class hierarchy, that is the class that directly contains metrics. On the other hand, the class handle is the representative name for all the elements in the naming hierarchy that define the DPD class name from "uma" up to (but not including) the terminal class identifier.

Providers

The MLI recognizes a provider as an explicit entity that registers and supplies metric classes and subclasses. As the DCI does not explicitly support this notion of provider, it is assumed, by convention, that the highest level class (or in some cases, classes) registered by a DCI provider be used to identify a provider entity (or entities).

The metadata classes, subclasses and structures returned by umaRequestConfig() are as follows:

UMAClassAttr

The UMAClassAttr structure provides the i18n (internationalization) and ASCII name labels for a class, identifies the metric-containing subclasses available in the class and provides labels for them. A set of structures for a single class is returned in a message of subclass "Class Attributes" in response to a MLI call umaRequestConfig() with a defined class handle and a subclass wildcard (UMA_ALLSUBCLASSES). It is also sent when there is a configuration change affecting the class if a umaStart() MLI call has been issued for class "UMA Configuration" subclass "Class Attributes" (or UMA_ALLSUBCLASSES).

The UMAClassAttr structure is defined as follows:

typedef struct UMAClassAttr {
  UMAClassId        class;          /* class handle              */
  UMAVarLenDescr    classLabel;     /* class label struct        */
  UMAArrayDescr     subClassId;     /* array of DPD sunclass ids */
  UMAArrayDescr     subClassStatus; /* subclass status array     */
  UMAVarArrayDescr  subClassLabel;  /* subcl label struct array  */
} UMAClassAttr;

This structure contains the class handle followed by a descriptor for its label (the actual label contents are in the UMA message UDU Basic Segment VLDS). These are followed by an array descriptor for the array of Data Pool subclass identifiers available in this class. (These subclass identifiers are the same as those registered by a DCI provider as class identifiers for classes that directly contain metrics.) For each subclass there is an element of a subclass-status array that describes the implementation status of the subclass, a value consisting of one of UMA_NOTIMPLEMENTED, UMA_DISABLED or UMA_ENABLED. Additional flag values in this array describe whether each subclass is available as INTERVAL data, EVENT data (or both).

The MLI service layer (the DSL) will compose a label to correspond to a class handle that is the concatenation, separated by periods, of the DCI class labels for each class in the path to the terminal, metric containing class.

Each subclass label is contained in a UMALabel structure defined as follows:

typedef struct UMALabel {
  UMAUint4         size;   /* size of this structure        */
  UMAVarLenDescr   ascii;  /* descriptor for the variable   */
                           /* UMATextString for ascii label */
  UMAElementDescr  i18n    /* descriptor for the variable   */
                           /* length data for i18n label    */
  UMAVarLenData    data;   /* label data for ascii and i18n */
} UMALabel;

UMASubClassAttr

The UmaSubClassAttr structure is the container for the metadata describing a UMA subclass. It includes descriptors for instance tags, work unit identifiers and metrics (data) corresponding to a given DCI metric class identifier. It is sent in a message of UMA class "Configuration", subclass "Subclass Attributes". This message is sent either when solicited by an UMARequestConfig() call or when there is a configuration change affecting the relevant UMA subclass and the "Configuration" subclass "Subclass Attributes" (or UMA_ALLSUBCLASSES) has been requested in a umaStart() call.

typedef struct UMASubClassAttr {
  UMASubClassHandles handles;      /* cl/subcl handles,flags    */
  UMAVarArrayDescr  instanceTags;  /* instance tag              */
                                   /* descriptor array          */
  UMAVarArrayDescr  workUnits;     /* work unit descr array     */
  UMAVarArrayDescr  dataBasic;     /* basic data desc array     */
  UMAVarArrayDescr  dataOptional;  /* optional data descr array */
  UMAVarArrayDescr  dataExtended;  /* extended data descr array */
} UMASubClassAttr;

UMASubClassHandles

The UMA class and subclass handles are contained in the UMASubClassHandles structure in messages of class "UMA Configuration", subclass "Subclass Attributes":

typedef struct UMASubClassHandles {
  UMAClass     class;          /* UMA class handle      */
  UMASubClass  subClass;       /* UMA subclass handle   */
} UMASubClassHandles;

The following figure shows how the UMASubClassAttr structure, which is contained in a UMA UDU of class "Configuration", subclass "Subclass Attributes" describes a UMA data UDU. In the figure, a data subclass is mapped that has its Data Pool Document (DPD) identifier provided in two components. The first component is an array of UMAClassId items that are the elements of the fully-qualified class name and the second component is just the subclass identifier by itself. These are mapped to the handles "X" and "Y", respectively.

Note that in the descriptor subclass "Subclass Attributes", the Basic Segment VLDS (Variable Length Data Section) contains variable length data that itself includes arrays of additional descriptive data structures. These structures will be defined in the ensuing discussion.

---

Figure: UMASubClassAttr Mapping to a Dynamic MLI Subclass

UMAInstTagDescr

UMA defines a fully qualified metric name as consisting of a class identifier, a metric instance identifier and a metric datum identifier. The metric class identifier is potentially multilevel and having multiple identifier components such as {data pool cpu per_thread}.

1. Metric Class Identifier
   The mapping of the class identifier proceeds by assigning its lowest level (rightmost) class identifier component to the UMA subclass id in the UMA SubClassAttr structure and the remaining set of higher level components (to the left of it) to the array of identifier components for the UMA class id in this same structure. These metric class id components represent the segment of a complete path to instantiated subclasses that are defined within a UMA Data Pool.

2. Instance Levels
   The metric instance identifier uniquely identifies a metric class instantiation for a specific system object. Like the DCI metric class identifier, the metric instance identifier may have multiple levels, however, at each level the number of bytes in the identifier may vary. As an example, consider {chan1 bus2 cont1 disk2} which represents a specific channel, bus, controller and disk.

   Metric instance identifiers are mapped level-by-level to instance tags in the UMA UDU and this mapping is described by the set of UMAInstTagDescr structures, one per level. Instance tags are special data items that appear in an MLI basic data UDU immediately following header information.

   typedef struct UMAInstTagDescr {
     UMAUint4        size;   /* size of this struct    */
     UMAUint4        flags;  /* indic mapped explicit, */
                             /* as data array indices  */
                             /* (lowest level only)    */
     UMADataType     type;   /* instance tag data type */
     UMAInstTagType  itType; /* instance tag type      */
     UMAUint4        itSize; /* tag size in bytes      */
     UMALabel        label;  /* ascii and i18n label   */
   } UMAInstTagDescr;
   
   

   When mapping to instance tags from instance identifiers, the order is preserved, meaning that the highest level component of the instance identifier appears (following the instance tag for the workload identifier) as the first instance tag, the next highest as the second instance tag, and so on. The instance tag data type determines whether the instance tag position in the metric data subclass fixed section for the segment is the tag data proper or if it is a data descriptor for variable length data, with the actual tag data in the data segment's VLDS pointed to by an offset in the descriptor. For example if the instance tag data type is UMA_UINT4, the tag data would be in the fixed data section, if the type is UMA_TEXTSTRING or UMA_OCTETSTRING, the fixed section would contain descriptors of type UMATextDescr or UMAElementDescr, respectively.

The UMAInstTagDescr structure describes levels of the metric instance identifier that are mapped explicitly to instance tags. However, the lowest level of the instance identifier may be mapped implicitly to an MLI UDU data array where this is deemed to be advantageous. In this case data type of the array index (corresponding to the instance tag data type) is always an integer. For example, the DCI_SYSCALL instance in the Data Pool Class "Processor", Subclass "Global System Call Counters" is mapped to an array with each index representing the numeric system call identifier.

UMAWorkDescr

The UMAWorkInfo definitions for a provider are a set of work units. These can be used jointly in a umaStart() specification to define filters and reporting granularities for per-work-unit subclasses. For example "Joe" might be a case of a work unit name corresponding to the UMAWorkInfo identifier "User Name" and "run_db" might be a case of a work unit name corresponding to the identifier "Command Name". When used jointly in the UMAWorkDefn of umaStart() structure they indicate that the Per Work-Unit subclass data is filtered for user "Joe" and the command "run_db". The available set of work unit identifiers depends on the provider type and is defined for for that provider type in the Data Pool.

There is some similarity between the UMAWorkInfo structure and instance identifiers and levels. A key difference is that a for a given provider type, a defined set of WorkInfo work unit identifiers is valid for all Per Work-Unit MLI classes and subclasses, while a fixed selection instance tags (UMA instance levels and types) are specifically defined for a particular MLI class and subclass. For example, only the instance types UMA_WORKID and UMA_PROCESSOR are valid in the Data Pool Subclass "Per Work Unit Processor Times", whereas any or all of the UMAWorkInfo identifiers defined for the provider may be used with this same subclass.

Another important difference between UMAWorkInfo and instance levels is that the implementation of UMAWorkInfo granularities is optional with any provider, while every provider must implement the instance levels as specified in the data pool. A provider has the following choices concerning the implementation of UMAWorkInfo:

1. Implement filtering as specified by a consumer's WorkInfo request for all or some of the UMAWorkInfo components,

2. Implement tagging only for all or some of the WorkInfo components,

3. Implement neither

The possible work unit identifiers supplied by a provider are defined by a set of UMAWorkDescr structures. This set of structures is contained in a message of UMA class "UMA Configuration", subclass "UMA Work Units" which is solicited with the umaRequestConfig() MLI call. The UMAWorkDescr structure is defined:

typedef struct UMAWorkDescr {
  UMAUint4        size;   /* size of this struct       */
  UMADataType     dType   /* Work Unit data type       */
  UMAWorkType     wType;  /* Work Unit type            */
  UMALabel        label;  /* ascii and i18n labels     */
} UMAWorkDescr;

UMADataAttr

The mapping of Data Pool metric values to the UMA Data UDU is described by the set of UMADataAttr structures. Data pool metric values are mapped to the same data types as defined in the Data Pool. Flag indicators in UMADataAttr indicate the implementation status of the item (UMA_NOTIMPLEMENTED, UMA_ENABLED or UMA_DISABLED) and whether the data is for the interval or is an absolute count. The descriptor type indicates whether the data is directly mapped at the offset or whether it is mapped through a descriptor to the UDU segment VLDS (Variable Length Data Section).

typedef struct UMADataAttr {
  UMAUint4        size;        /* size of this struct     */
  UMADataType     type;        /* data type of metric     */
  UMAUint4        status;      /* status: NOTIMPLEMENTED, */
                               /* DISABLED, ENABLED       */
  UMAUnit         units;       /* data units              */
  UMAUint4        dataFlags;   /* flags on units          */
                               /* rates, counts,          */
                               /* intervalization         */
  UMAUint4        offset;      /* to data item or descr   */
                               /* from segment start      */
  UMADescrType    descrType    /* Descriptor type         */
                               /* (or none)               */
  UMALabel        label;       /* ascii and i18n labels   */
} UMADataAttr;  

DISCOVERY OF PROVIDERS, CLASSES, AND SUBCLASSES

This section summarizes the behavior of the MLI UMARequestConfig() call as used to discover what providers have registered and to discover what classes and subclasses are available for a given provider.

Wildcards

The defined values UMA_ALLCLASSES and UMA_ALLSUBCLASSES are wildcards for MLI classes and subclasses, respectively.

Available

Executing the MLI call umaRequestConfig() with a class wildcard (UMA_ALLCLASSES), a subclass "UMA Providers", returns a message of class "UMA Configuration" and subclass "UMA Providers" that contains a list of providers available for this session's destination. The provider, dclass and dsubcls specifications are ignored. This class and subclass specification is also available to umaStart() as an event.

Available

Executing the MLI call umaRequestConfig() with a class wildcard (UMA_ALLCLASSES) and a subclass of "Implementation" returns a message of class "UMA Configuration" and subclass: "Implementation" that contains the status arrays for the classes and subclasses defined for the provider. These include both built-in and dynamic classes and subclasses. This class and subclass specification is also available to umaStart() as an event.

Available

Executing the MLI call umaRequestConfig() with a defined class handle and a subclass "Class Attributes" returns the subclass "Class Attributes" of class "UMA Configuration". This returns the identifiers, labels and status of either built-in or dynamic subclasses. This class and subclass specification is also available to umaStart() as an event.

Retrieving

Executing the MLI call umaRequestConfig() with both class and subclass handles other than for the class "UMA Configuration" returns a message of class "UMA Configuration" and of subclass "Subclass Attributes".

Possible

Executing the MLI call umaRequestConfig() with a class handle of UMA_ALL_CLASSES and a subclass of "UMA Work Units" returns a message of class "UMA Configuration" and of subclass "UMA Work Units".

---

umaRequestConfig()

The following table summarizes the use of the umaRequestConfig() call for obtaining UDU message descriptions. For, simplicity, the effects of the UMA_REPORT_DYNAMIC flag has been omitted from this table.

		Returns
Specified Class	Specified Subclass	"UMA Configuration"	For
		Subclass
UMA_ALLCLASSES	"UMA Providers"	"UMA Providers"	All available providers for this sysid
UMA_ALLCLASSES	"Implementation"	"Implementation"	All metric classes and subclasses for the provider
	"States"	"States"
	etc.	etc.
<	class handle>		"Implementation"
All metric subclasses in class denoted by Class Handle
T}
		"Class Attributes"
<	class handle>		"Subclass Attributes"
All metric subclasses in class denoted by Class Handle
T}
UMA_ALLCLASSES	"Work Units"	"Work Units"	All UMAWorkInfo work units possible for this provider
UMA_ALLCLASSES	UMA_ALLSUBCLASSES	All of the above class/subclass information subclasses	All configuration and metric classes for the provider

NOTES

UMA_ALLCLASSES implies UMA_ALLSUBCLASSES.

umaRequestConfig() call responses are always returned to the originating MAP, regardless of the specified destination. These same status classes and subclasses may be directed to the session-specified destination as event data, by specifying them in umaStart() calls.

The umaRequestConfig() call differs from umaStart() in that it solicits an out-of-band response and does so only once for each solicitation.

---

DIAGNOSTICS

The returned value of umaRequestConfig() indicates the general outcome (status code). Supplementary reason code for a failed status can be obtained by calling the umaGetReason() function. Status and reason codes that apply to umaRequestConfig() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_CLASS	UMR_PERMISSION	Access denied to this configuration data
	UMR_DISABLED	Specified configuration class not available
	UMR_INVALID	Specified configuration class invalid
	UMR_NOTIMPLEMENTED	Specified configuration class not implemented
UMS_COMM	UMR_SEND	Communications error when sending messages to UMA
UMS_EOS	-	End of session encountered
UMS_PROVIDER	UMR_PERMISSION	Access denied to this provider
	UMR_UNKNOWN	Unknown data provider
UMS_SESSID	-	Invalid sessid specified
UMS_SESSION	UMR_RESOURCE	Lack of some system resources
UMS_SUBCLASS	UMR_DISABLED	Specified configuration subclass not available
	UMR_INVALID	Specified configuration subclass invalid
	UMR_NOTIMPLEMENTED	Specified configuration subclass not implemented

NAME

umaSeek - reposition to the interval of data with the specified timestamp.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaSeek(
UMASessId sessid, /* in */
UMAInt4 position, /* in */
UMAWhence whence, /* in */
UMATimeSpec *tstamp /* in */
);

DESCRIPTION

The starting time for data reporting is nominally defined by the stime session parameter. Reporting normally continues forward from this point. However, it is also possible to position reporting by seeking to times either in Recent Data or UMADS facilities using umaSeek().

umaSeek() specifies that the next reporting interval corresponds to time tstamp, offset by number of intervals specified in the signed integer position.

1. The parameter position may be zero, negative, or positive.

2. The parameter tstamp may be any one of the following (subject to the values of the session attributes RECENT_ONLY and HISTORY_ONLY):

   • If the whence parameter is UMA_TSTAMP, the seek is relative to an arbitrary timestamp of type UMATimeSpec specified in the tstamp parameter.

   • A defined value UMA_CTIME, that specifies the session current time setting (timestamp of the last message retrieved by umaGetmsg(),

   • A defined value UMA_LTIME, that specifies the latest time available from the source, subject to the constraint that the specified session end time is not exceeded,

   • A defined value UMA_STIME, that specifies the session start time.

If the session attribute RECENT_ONLY is set to TRUE, then seeks are confined to the data intervals in the Recent Data Facility.

If the session attribute HISTORY_ONLY is set to TRUE, then seeks are confined to UMADS.

All specified data collection (as opposed to reporting) continues during umaSeek() operations. The new data is not reported until it is reached in time sequence.

Note that the effect of a successful umaSeek() call is immediate, in that the next umaGetMsg() call will access data or status messages resulting from the repositioning. umaSeek() is defined only for sessions whose destination is the MAP.

If any of the session attributes STIME, ETIME, or INTERVAL have not been set, no positioning action will be taken and umaSeek() will return a UMS_ATTR status code with reason code UMR_INCOMPLETE.

NOTES

If a umaSeek() call is made to a time prior to the STIME, the next call to umaGetMsg() will return a message of class: UMA_CONDITION, subclass: UMA_INFO, source: UMA_DSL, id: UMA_STIME_BOUNDS. A subsequent call to umaGetMsg()() will return data from the first interval in the session.

f a umaSeek() call is made to a time prior to the ETIME, the subsequent calls to umaGetMsg() will return a message of class: UMA_CONDITION, subclass: UMA_INFO, source: UMA_DSL, id: UMA_EOS.

A seek with position 0 and UMA_CTIME will "reposition" to the current message. This will cause the next umaGetmsg() to return this same message.

A seek with UMA_LTIME must have a zero or negative position, otherwise an error return of status UMS_TIME, reason UMR_CONFLICT will result.

The following may result in unpredictable positioning:

1. A umaSeek() call with UMA_CTIME (current time) used prior to a umaGetmsg() call,

2. Two consecutive calls to umaSeek() with no intervening successful call to umaGetmsg().

DIAGNOSTICS

The returned value of umaSeek() indicates the general outcome (status code). Supplementary reason code for a failed status can be obtained by calling the umaGetReason() function. Status and reason codes that apply to umaSeek() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_ATTR	UMR_INCOMPLETE	All required attributes not specified
UMS_COMM	UMR_SEND	Communications error when sending messages to UMA
	UMR_SYSERR	System error while communicating with UMA
	UMR_RECEIVE	Communications error while receiving messages from UMA
UMS_DEST	UMR_CONFLICT	Seek undefined with session destination
UMS_EOS	-	End of session encountered
UMS_SESSID	-	Invalid sessid specified
UMS_SESSION	UMR_RESOURCE	Insufficient system resources
UMS_TIME	UMR_CONFLICT	Conflicting time positions specified
	UMR_INVALID	Invalid time positions specified

NAME

umaSetAttr - specify (or change) a session's attributes.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaSetAttr(
UMASessId sessid, /* in */
... /* in */
);

DESCRIPTION

Once a session is established (by a umaCreate() call), a MAP can issue a umaSetAttr() call to set or change the attributes for the session denoted by sessid.

The sessid parameter is followed by a null-terminated variable length list of name-value pairs (attrpairs), each pair consisting of a quoted attribute name followed by a comma and the attribute value. (Example: "PRIO", 5).

The session attributes and their defaults are:

Attribute	Type	Default by Source
		_
		File	UMADS	RECENT	UMADS+RECENT
STIME	UMATimeSec	Min Time	None	UMA_TIME_NOW	None
ETIME	UMATimeSec	Max Time	None	UMA_TIME_MAX	UMA_TIME_MAX
INTERVAL	UMATimeSec	File	UMADS	None	None
PRIO	UMAPrio	3	3	3	3
HISTORY_ONLY	UMABoolean	TRUE	TRUE	FALSE	FALSE
RECENT_ONLY	UMABoolean	FALSE	FALSE	TRUE	FALSE
PARTIAL	UMABoolean	FALSE	FALSE	FALSE	FALSE

The settings of these attributes affects the session context for other MLI calls in the following ways.

Data reporting for the specified session will be for intervals of size specified by attribute INTERVAL from STIME to ETIME.

Unless the session property UMA_NOTREGULAR has been set, intervals will be regular meaning:

1. If the number of seconds is greater than or equal to 3600 (1 hour), then the number of seconds must integrally divide 24*3600 and the equivalent number of hours must be a whole number. This is equivalent an interval specification of 1, 2, 3, 4, 6, 8, 12, or 24 hours.

2. If the number of seconds is greater than or equal to 60 but less than 3600, then the number of seconds must integrally divide 3600 and the equivalent number of minutes must be a whole number. This is equivalent to an interval specification of 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, or 30 minutes.

3. If the number of seconds is less than 60, then the number of seconds must integrally divide 60. This is equivalent to an interval specification of 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, or 30 seconds.

In any case, the interval duration must not be greater than 24 hours.

If the session start time or the reporting request (umaStart()) occurs at a time between regular collection times, the first interval reported for the session may be for a shorter duration than that specified. All subsequent collections will be of the correct duration and at regular times.

The STIME and ETIME attributes are specified in units of calendar time measured in seconds since January 1, 1970 and are expressed as Coordinated Universal Time. The defined constant UMA_TIME_NOW may be used as a value for STIME or ETIME to specify an immediate start time or end time, respectively. The defined constant UMA_TIME_MIN may be used as a value for STIME to specify a session start time prior to any recorded data. The defined constant UMA_TIME_MAX may be used as a value for ETIME to specify that the end time is indefinite and that the session will be ended by an explicit umaClose() call.

If the session property UMA_NOTERM is set (in umaCreate()) and the time specified by ETIME is reached, the session is automatically closed. If UMA_NOTERM is not set, a notification message is sent to the issuing MAP indicating end-of-session reached, in which case the MAP may either seek back in time or close the session. Note that setting the ETIME attribute to UMA_TIME_NOW results in an immediate end of reporting.

Note that the attributes STIME and ETIME must be specified prior to any umaGetMsg(), umaRequestConfig() and umaSetThreshold() calls. In addition, INTERVAL must be specified prior to a umaRelease() that contains start or stop requests that have specified interval data.

The session start time STIME may be changed at any time before a previously specified start time has occurred. Once this time has passed, however, it can only be changed to an earlier time.

The effect of setting the STIME attribute when a session is initialized is to position the session's current time pointer to this value. Subsequent changes to the STIME attribute do not change the session's current time pointer.

The reporting end time ETIME may also be changed at any time before a previously specified time has occurred. Once this time has passed, it may be extended by a MAP destination ("UMA_MAP") to a later time. For a file or UMADS destination, however, the session will be atomatically closed when this time is reached. See also the umaGetMsg() description for status and reason codes when the destination is a MAP.

Positive values of INTERVAL are taken to be the reporting interval size in seconds. A zero specification for INTERVAL is an error when the session source contains "RECENT" as part of its specification. When the source is UMADS or a file, a specified interval of zero is treated as a wildcard in that data is reported at the stored interval value in those sources; any positive integer interval specification is ignored in these cases. Alternatively, if the INTERVAL attribute is the defined constant UMA_TIME_MAX, a single interval will be defined from the time of first reporting to the session end time or the session close. This last capability is useful for collections that are to last the duration of a programmatically determined interval, as may happen in benchmarking activities.

The INTERVAL attribute does not affect data requested for reporting as events; reporting of events is on an individual basis for each event occuring in the start/stop window.

The relative priority of data delivery to the MAP, is designated by the PRIO attribute, a non-negative integer, with increasing values indicating decreasing priorities. This priority is in effect only when retrieving data with the umaGetMsg() call and specifying the defined value UMA_ANYSESSION for the requested session. (See umaGetMsg()).

The session attributes HISTORY_ONLY and RECENT_ONLY limit searches to UMADS or to the Recent Data Facility, respectively, when source has been specified as "UMADS + RECENT". For further details, see the descriptions for these attributes under attrparams in MLI Call Parameters .

When regular intervals are in effect, setting the session attribute PARTIAL to TRUE indicates that a requested change of interval size can take place at the next regular collection time for the shorter of the new and old intervals. This specification may result in a single truncated old or new interval at the time the change is made.

Summary of Data Source Specification

The following table shows the effect of various selections of source parameters and the session attributes RECENT_ONLY and HISTORY_ONLY in UMA. An attempt to set both RECENT_ONLY and HISTORY_ONLY to TRUE results in an error.

umaCreate() source	RECENT_ONLY	HISTORY_ONLY	Source Used
RECENT	FALSE	FALSE	Error
RECENT	TRUE	FALSE	Recent Data
RECENT	FALSE	TRUE	Error
UMADS	FALSE	FALSE	UMADS
UMADS	TRUE	FALSE	Error
UMADS	FALSE	TRUE	UMADS
UMADS + RECENT	FALSE	FALSE	Recent Data and UMADS
UMADS + RECENT	TRUE	FALSE	Recent Data
UMADS + RECENT	FALSE	TRUE	UMADS
Private File	FALSE	FALSE	Error
Private File	TRUE	FALSE	Error
Private File	FALSE	TRUE	Private File

---

EXAMPLE

The following example assumes that there is an active session with a sessid of sessid1. The function timec() in the example converts a string valued time specification to seconds since January 1, 1970).

#include <uma.h>

UMAStatusCode status;
UMASessId sessid1;

status = umaSetAttr(sessid1, "STIME", timec("2pm"),
"INTERVAL", 120, "PRIO", 1,
"RECENT_ONLY", TRUE, (char*)NULL);

DIAGNOSTICS

In the case of an error, no action will be taken on any specified attributes. The returned value of umaSetAttr() indicates the general outcome (status code). Supplementary reason code for a failed status can be obtained by calling umaGetReason(). Status and reason codes that apply to umaSetAttr() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_ATTR	UMR_INVALID	Invalid attribute name specified
	UMR_CONFLICT	Attributes conflict
UMS_COMM	UMR_SEND	Communications error when sending messages to UMA
UMS_EOS	-	End of session
UMS_INTERVAL	UMR_INVALID	Invalid interval duration specified
	UMR_CONFLICT	Interval conflicts with source/destination
UMS_PRIORITY	UMR_INVALID	Invalid priority specified
UMS_SESSID	-	Invalid sessid
UMS_SESSION	UMR_RESOURCE	Resource not available
UMS_TIME	UMR_INVALID	Invalid time specified
	UMR_CONFLICT	STIME/ETIME conflict with other attribute

NAME

umaSetThreshold - establish or change UMA threshold values.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaSetThreshold(
UMASessId sessId, /* in */
UMAProvider provider, /* in */
UMAClass class, /* in */
UMASubClass subClass, /* in */
UMASegFlags segment, /* in */
char *selectExpr /* in */
char *workload /* in */
);

DESCRIPTION

The function umaSetThreshold() formats a message to the UMA facility to report data for a class, subClass and segment from provider as specified in a prior umaStart() call in this same session, only if the selection expression selectExpr evaluates to TRUE. Filtering may be reset either by field or for an entire selection expression using the reset expression resetExpr. The action of umaSetThreshold() can be restricted to a previously defined constructed workload (see umaStart()) by use of the workload parameter. A NULL pointer for workload indicates that the umaSetThreshold() action is to be global.

Note that umaSetThreshold() calls do not take effect until a umaRelease() call is made. This same umaRelease() call can contain umaStart() calls in its scope, as long as they precede the related umaSetThreshold() call(s). Multiple calls for the same session, provider, class and subClass are ORed, meaning that if any one of the selection expressions evaluates to TRUE, the designated subclass segments are reported to the calling MAP. If a umaSetThreshold() call is made referencing an unstarted class, subclass, or segment, no action is taken and the status UMS_SUBCLASS and reason UMR_NOTSTARTED are returned.

A select expression is defined as follows:

select_expr:


      <compare_expr> 


    | <compare_expr> <lo> <select_expr>


    | <reset_expr>





lo:


      '|'  /* or */


    | '&'  /* and */





compare_expr:


      <field_des> <ro> <numeric_value>





reset_expr:


      RESET              /* Resume segment reporting    */


    | <field_des> RESET  /* Reset at the field level    */





ro:


      LT   /* less than                */


    | LE   /* less than or equal to    */


    | EQ   /* equal to                 */


    | GT   /* greater than             */


    | GE   /* greater than or equal to */


    | NE   /* not equal to             */


    | NLT  /* not less than            */


    | NGT  /* not greater than         */





field_des:


      $<field_index>    /* ith scalar field in UMA data  */


                        /* message or any element,       */


                        /* if an array                   */


    | $<namespace_ref>  /* Data Pool namespace reference */


                         


field_index:


      <integer>





namespace_ref:


      <DP  xref>  /* Fully qualified Data Pool xref      */


                  /* including the enclosing < > marks.  */


numeric value:


      a value convertible by %f input conversion in C.

As the logical operator '&' has higher precedence than '|',
parentheses may be required to indicate the desired meaning. In
addition, the relational operators (ro) have a higher precedence than
the logical operators (lo).

EXAMPLES

"$3 GT 75"





"$5 LE 10 | $6 GT 50"





"$5 LE 10 & ($7 GT 60 | $9 GE 70)"





"$<2.1.93> GT 10 & $<2.1.94> GT 5)"   /* DCI xrefs */





"$5 RESET"  /* Remove $5 from filtering expression */

DIAGNOSTICS

The returned value of umaSetThreshold() indicates the general outcome
(status code). Supplementary reason code for a failed status can be
obtained by calling the umaGetReason() function.
Status and reason codes that apply to umaSetThreshold() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_CLASS	UMR_DISABLED	Specified class not available
	UMR_INVALID	Specified class invalid
	UMR_NOTIMPLEMENTED	Specified class not implemented
UMS_COM	UMR_SEND	Communications error when sending to UMA
UMS_EXPRESSION	UMR_INVALID	Invalid selection expression
UMS_FIELD	UMR_DISABLED	Specified field disabled
	UMR_INVALID	Specified field invalid
	UMR_NOTIMPLEMENTED	Specified field not implemented
UMS_SESSID	-	Invalid session specified
UMS_SUBCLASS	UMR_DISABLED	Specified subclass disabled
	UMR_INVALID	Specified subclass invalid
	UMR_NOTIMPLEMENTED	Specified subclass not implemented

NAME

umaStart - specify the classes and subclasses of data to be reported.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaStart(
UMASessId sessid, /* in */
UMAProvider provider, /* in */
UMAClass class, /* in */
UMASubClass subClass, /* in */
UMASegFlags segFlags, /* in */
UMAWorkDefn *workDefn /* in */
);

DESCRIPTION

The function umaStart() specifies the class and subclass of data to be reported for the session denoted by sessid. Data reporting will be started for the specified provider, class, and subClass. (UMA will initiate data collection, if necessary). The defined symbols UMA_ALLCLASSES and UMA_ALLSUBCLASSES may be used for class and subClass respectively, to indicate that all classes and all subclasses are to be selected. Note that UMA_ALLCLASSES implies UMA_ALLSUBCLASSES.

Either interval or event forms of reporting may be selected for subclasses where these forms are defined to be valid in the Data Pool Definitions (see reference DPD). Events are usually reported out-of-band, that is they are reported ahead of any other currently queued data messages. In-band delivery can be specified using the UMAWorkDefn structure described below.

The Data Pool Definition (see reference DPD), describes three conceptual data segments or groupings within a UMA data subclass:

1. Basic - This is a segment of universally supplied data for the subclass as defined by the Measurement Data Pool.

2. Optional - This is a segment of data whose structure and contents are defined by the Measurement Data Pool but this segment may or may not be present in a particular implementation.

3. Extension - This is data whose structure and contents are defined by a specific vendor or reseller for the system. This segment may or may not be present.

segFlags indicates which data segments are to be reported (UMA_BSEG, UMA_OSEG and UMA_ESEG for basic, optional, and extension, respectively).

destination (set in the umaCreate() call) controls whether the data is reported to the requesting MAP or if it is to be recorded in UMADS or in an output file.

Normally, UMA will wait to start collection and reporting after a umaRelease() call is made subsequent to the umaStart(), however the umaStart() will not actually take effect until the session attributes STIME, ETIME, INTERVAL have been set.

In addition, umaStart() requests will be validated and assembled within UMA but not acted upon until two conditions are satisfied:

1. the time specified by attribute STIME has occurred

   and

2. a umaRelease() call has been made.

This will allow a coordinated start time for a set of session measurements within the time window defined by attributes STIME and ETIME

Specification of UMAWorkInfo values and instances for reporting will be by use of the UMAWorkDefn structure defined as follows:

typedef struct UMAWorkDefn {
  UMAUint4          size;          /* size of this struct     */
  UMAUint4          rFlags;        /* reporting flags         */
  UMATextDescr      workIdSpec;    /* workload id offset/size */
  UMAUint4          granularity;   /* granularity request     */
  UMAUint4          wFlags;        /* workload  flags         */
  UMAVarLenDescr    workInfoSpec   /* offset to WorkInfo data */
  UMAVarLenDescr    instanceSpec   /* offset to instance data */
  UMAVarLenData     data;          /* WorkInfo, instance specs*/
} UMAWorkDefn;

The UMAWorkDefn structure provides the definition of a constructed workload and specification under the control of a number of flags described below. If the structure pointer for workDefn in the input parameters is NULL, then UMAWorkInfo selection, instance selection, workload selection by identifier, or summarization will not be requested.

The workload specification flags include:

UMA_WORKLOAD_ABSOLUTE

Requests that this workload be defined by use of absolute (not intervalized) counters for this class and subclass.

UMA_WORKLOAD_COMPLEMENT

Requests that this definition is of a complement constructed workload, meaning that a metric values in this workload consist of those available in the corresponding global metric class and subclass minus the values of the corresponding metrics in this per-work-unit class and subclass.

UMA_WORKLOAD_SUMMARIZED

Requests that the data for this constructed workload be summarized to level specified in the UMAWorkDefn structure granularity flag even if the data provider to UMA does not directly support this granularity. Satisfying this request does however depend on the data provider's being able to tag this UMAWorkInfo level. This is indicated in the metadata provided by the UMA message of class "Configuration", subclass "Subclass Attributes" as a supported UMAWorkInfo level. A request for summarization at a granularity level that is not available is an error (UMS_WORKLOAD, UMR_GRANULARITY).

The reporting specification flags include:

UMA_REPORT_DYNAMIC

Requests that the DCI return structure form of this subclass (Canonical A) should be reported by the MLI. Otherwise, the built-in structure form (Canonical C) is reported.

UMA_REPORT_EVENT

Requests that the asynchronous event form of the specified class and subclass be reported to the MAP.

UMA_REPORT_WORKLOAD

Requests that the workload data form of the specified class and subclass be reported to the MAP.

UMA_EVENT_FINALDATA

Requests that the final data event for the specified class and subclass be reported to the MAP. Final data can be reported on components of the workload requested via the selection criteria to the extent supported by the data provider. For example, if commands "abc*" are selected for user 123, then, final data will reported whenever each such command teminates.

UMA_EVENT_INBAND

Requests that event messages of the specified class and subclass be delivered to the MAP in_band, that is, they are to be reported in time sequence along with any queued data messages.

The UMAWorkSpec structure for specifying selection of UMAWorkInfo values is defined:

typedef struct UMAWorkSpec {
  UMUint4           wSpecSize;  /* size of this structure     */
  UMAUint4          wSelect;    /* WorkInfo level select bits */
  UMAVarArrayDescr  wSpecDescr; /* WorkInfo specs descr       */
  UMAVarLenData     data;       /* WorkInfo level spec value  */
} UMAWorkSpec;

And each WorkInfo level specification is in a UMAWorkLvlSpec structure:

typedef struct UMAWorkLvlSpec {
  UMAUint4        wLvlSize;    /* size of this structure    */
  UMAUint4        wLvlType;    /* enum type of WorkInfo spec*/
                               /* UMA_TEXTSTRING,           */
                               /* UMA_UINT4, etc assigned   */
  UMAVarLenData   data;        /* work spec/expr            */
} UMAWorkLvlSpec;

Note that the descriptor entries workIdSpec, workInfoSpec measure offsets from the start of their containing structure, UMAWorkDefn, and wSpecDescr measures offset from the start of UMAWorkSpec. Also, each structure's initial size field (of type UMAUint4) is preceded by sufficient padding so that the size field begins on a 4-byte word boundary.

The UMAWorkInfo levels and their data types are described by the UMAWorkDescr structures contained in a UMA message of class "UMA Configuration", subclass "WorkInfo Attributes". If the data type in UMAWorkDescr is text, a text regular expression may be used for selection in UMAWorkLvlSpec ². If the UMAWorkInfo data type is integer, either an integer or a text regular expression with integer semantics may used as a selection specification (e.g. a range such as [22-25] ). A wildcard integer value '0xffffffff' specifies that all UMAWorkInfo values are to be selected.

The UMAInstSpec structure for specifying selection of instances is defined:

typedef struct UMAInstSpec {
  UMAUint4          iSpecSize;   /* size of this structure     */
  UMAUint4          iSelect;     /* instance level select bits */
  UMAVarArrayDescr  iSpecsDescr; /* instance level specs descr */
  UMAVarLenData     data;        /* instance level spec values */
} UMAInstSpec;

And each instance level specification is defined using the UMAInstLvlSpec structure:

typedef struct UMAInstLvlSpec {
  UMAUint4        iLvlSize;    /* size of this structure    */
  UMAUint4        iLvlType;    /* enum type of instance spec*/
                               /* UMA_TEXTSTRING,           */
                               /* UMA_UINT4, etc assigned   */
  UMAVarLenData   data;        /* instance spec/expr  */
} UMAInstLvlSpec;

Here again, the descriptor entries (instanceSpec, iSpecsDescr) measure offsets from the start of their containing structures (UMAWorkDefn and UMAInstSpec, respectively), and each structure's initial size field (of type UMAUint4) is preceded by sufficient padding so that the size field begins on a 4-byte word boundary.

The instance levels and their data types are described by the UMAInstTagDescr structures in a UMA message of class "UMA Configuration", subclass "Subclass Attributes". If the instance level data type is integer, either an integer or a text regular expression with integer semantics may used as a selection specification (e.g. a range such as [22-25] ). A special wildcard integer value '0xffffffff' specifies that all instance values are to be selected.

As an example using the Unix Data Pool Definitions, consider a UMAWorkDefn structure that requests reporting granularity at the process level for command names commencing with the letters abc (UMAWorkInfo command name), executing on processors 2 through 4 (processor instances). The layout of the UMAWorkDefn structure would be as follows (assuming a compiler that aligns UMAUint4 on 4-byte word boundaries):

0x0000006c                /* size of this structure (108)      */
UMA_REPORT_WORKLOAD       /* report workload flag (rFlags)     */
0x00000020                /* offset to workload id (32)        */
0x00000007                /* size of workload id               */
UMA_WORKINFO_PROCESS_ID   /* report process granularity        */
0x00000000                /* workload is intervalized (wFlags  */
0x00000024                /* offset to WorkInfo data (36)      */
0x00000048                /* offset to instance data (72)      */
"work001"                 /* workload identifier               */
0x0                       /* padding (1 byte)                  */
0x00000021                /* size of UMAWorkSpec structure (36)*/
UMA_WORKINFO_COMMAND_NAME /* WorkInfo selection by command     */
0x00000010                /* offset to array of wrk selns (16) */
0x00000001                /* array count is 1 item (command)   */
0x00000017                /* size of UMAWorkLvlSpec struct     */
0x00000007                /* type is UMA_TEXTSTRING (enum)     */
0x00000009                /* size of text string struct (9)    */ 
"abc.*"                   /* regexpr string for command        */
0x000000                  /* padding (3 bytes)                 */
0x00000024                /* size of UMAInstSpec structure (36 */
UMA_PROCESSOR             /* bit value for processor instance  */
0x0000000f                /* offset to array of inst selections*/
0x00000001                /* array count is 1 item (processor) */
0x00000011                /* size of UMAInstLvlSpec struct (17)*/
0x00000007                /* type is UMA_TEXTSTRING (enum)     */
0x00000009                /* size of text string struct (9)    */ 
"[2-4]"                   /* processor 2 through 4 selection   */
0x000                     /* padding (3 bytes)                 */

Note that The double-quote (") is used here to indicate that the content of the data field is text, that is, the quote does not appear in the data.

DIAGNOSTICS

The returned value of umaStart() indicates the general outcome (status code). Supplementary reason code for a failed status can be obtained by calling the umaGetReason() function. Status and reason codes that apply to umaStart() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_CLASS	UMR_DISABLED	Specified class not available
	UMR_INVALID	Specified class invalid
	UMR_NOTIMPLEMENTED	Specified class not implemented
	UMR_PERMISSION	Access denied to this class/subclass
UMS_COMM	UMR_SEND	Communications error when sending messages to UMA
UMS_EOS	-	End of session
UMS_EVENT	UMR_NOTIMPLEMENTED	Event not implemented
UMS_FLAGS	UMR_INVALID	Specified flag is invalid
UMS_NODE	UMR_UNKNOWN	Node not recognised
UMS_PROVIDER	UMR_PERMISSION	Access denied to this provider
	UMR_UNKNOWN	Unknown data provider
UMS_SESSID	-	Invalid session specified
UMS_SESSION	UMR_RESOURCE	Resource not available
UMS_SUBCLASS	UMR_DISABLED	Specified subclass not available
	UMR_INVALID	Specified subclass invalid
	UMR_NOTIMPLEMENTED	Specified subclass not implemented
UMS_WORKLOAD	UMR_GRANULARITY	Workload granularity not supported
	UMR_REGEXP	Invalid regular expression

NAME

unaStop - stop reporting of data classes and subclasses.

SYNOPSIS

#include <uma.h>

UMAStatusCode umaStop(
UMASessId sessid, /* in */
UMAProvider provider, /* in */
UMAClass class, /* in */
UMASubClass subClass, /* in */
UMASegFlags segFlags, /* in */
UMAFlushFlags flushFlags, /* in */
UMAWorkDefn *workDefn; /* in */
);

DESCRIPTION

umaStop() requests the UMA facility to stop reporting the data specified by provider, class, subClass, and, optionally, a workload as defined in workDefn over sessid. If the pointer to the UMAWorkDefn structure is not NULL, umaStop() terminates reporting on the specified class and subclass. This action can be limited to a specified workload and/or workload components by optionally specifying them in a UMAWorkDefn structure parameter. (Note that collection may continue if other sessions have requested the same subclass.)

The defined symbols UMA_ALLCLASSES and UMA_ALLSUBCLASSES may be used for class and subclass, respectively, to indicate that all classes and all subclasses are to be stopped. Note that the symbol UMA_ALLCLASSES implies UMA_ALLSUBCLASSES.

The segFlags parameter indicates which data segments are to be stopped (UMA_BSEG, UMA_OSEG, UMA_ESEG, UMA_ASEG for basic, optional, extension, and all, respectively). Not specifying segflags is equivalent to having specified UMA_ASEG.

The flushFlags parameter further specifies which previously issued umaStart()s are cancelled. The flag settings include UMA_ALLSTARTED, UMA_HELD, or UMA_RELEASED to indicate whether all requests or only those held or only those released are to be stopped.

In addition to specifying a class and subclass to be stopped, the caller can specify that reporting of a previously defined workload or class/subclass components be terminated for this session using the UMAWorkDefn structure (see umaStart() for a full description of the structure). The fields in the UMAWorkDefn structure that are used and not used by umaStop() are shown here:

typedef struct UMAWorkDefn {
    UMAUint4        size;         /* size of this struct     */
    UMAUint4        rFlags;       /* reporting flags         */
    UMATextDescr    workIdSpec;   /* workload id offset/size */
    UMAUint4        granularity;  /* not used in umaStop()   */
    UMAUint4        wFlags;       /* not used in umaStop()   */
    UMAVarLenDescr  workInfoSpec  /* not used in umaStop()   */
    UMAVarLenDescr  instanceSpec  /* not used in umaStop()   */
    UMAVarLenData   data;         /* not used in umaStop()   */
} UMAWorkDefn;

Unused fields of type UMAVarLenData must have valid size components but any contained data will be ignored by umaStop(). The workload identifier (work_id) limits the action of umaStop to the specified workload. If it is a null string, the reporting flags (rFlags) can still be used to stop components for all workloads:

UMA_REPORT_EVENT

Requests that reporting of the asynchronous event form of the specified class and subclass be terminated (for this workload identifier).

UMA_REPORT_WORKLOAD

Requests that the reporting of the workload data form of the specified class and subclass be terminated (for this workload identifier).

UMA_EVENT_FINALDATA

Requests that the reporting of final data event for the specified class and subclass be terminated (for this workload identifier).

UMA_EVENT_INBAND

Requests that in-band reporting of event messages of the specified class and subclass be changed to out-of-band reporting if event reporting is still to be continued (for this workload identifier).

---

DIAGNOSTICS

The returned value of umaStop() indicates the general outcome (status code). Supplementary reason code for a failed status can be obtained by calling the umaGetReason() function. Status and reason codes that apply to umaStop() include:

STATUS	REASON	EXPLANATION
UMS_SUCCESS	UMR_NOREASON	No error encountered
UMS_CLASS	UMR_DISABLED	Specified class not available
	UMR_INVALID	Specified class invalid
	UMR_NOTIMPLEMENTED	Specified class not implemented
UMS_COMM	UMR_SEND	Communications error when sending messages to UMA
UMS_EOS	-	End of session
UMS_EVENT	UMR_NOTIMPLEMENTED	Event not implemented
UMS_FLAGS	UMR_INVALID	Specified flag invalid
UMS_NODE	UMR_UNKNOWN	Specified node not recognised
UMS_PROVIDER	UMR_UNKNOWN	Unknown data provider
UMS_SESSID	-	Invalid session specified
UMS_SESSION	UMR_RESOURCE	Resource not available
UMS_SUBCLASS	UMR_DISABLED	Specified subclass disabled
	UMR_INVALID	Specified subclass invalid
	UMR_NOTIMPLEMENTED	Specified subclass not implemented

Footnotes

1.

For example, UNIX_DATAPOOL, is the operating system provider for Unix-based systems.

2.

More specifically, a Basic Regular Expression as defined in the XSI Specification.