Status

Short Description

Polls the SAS Metadata Server for status, platform version, SAS Metadata Model version, server locale, server configuration information, and journaling statistics.

Syntax

rc=Status(inmeta,outmeta,options);

Method Parameters

Parameter	Type	Direction	Description
rc	N	out	Return code for the method. Indicates whether the SAS Metadata Server ran the method call. RC=0 means that it did, RC=1 means that it did not.
inmeta	string	in	Specifies one or more XML elements that requests information from the SAS Metadata Server. If no elements are specified, the Status method returns values for the <MODELVERSION/>, <PLATFORMVERSION/>, <SERVERSTATE/>, <PAUSECOMMENT/>, and <SERVERLOCALE/> XML elements, by default. Other supported XML elements include: <BACKUP attribute(s)/> Queries the progress of an active server backup or server recovery operation. Valid attributes are BYTESTOCOPY="", BYTESCOPIED="", and ISRUNNING="". <BACKUPCONFIGURATION/> Returns the active server backup configuration. For more information, see Using Backup and Recovery XML Elements. <METADATASERVERBACKUPHISTORY/> Lists a history of the backup and recovery activity on the SAS Metadata Server. For more information, see Using Backup and Recovery XML Elements.
			<METADATASERVERBACKUPMANIFEST optional-attribute/> Lists the metadata repositories, metadata server journal file, and configuration files copied in the last backup for validating the backup. Supports the BACKUPNAME="name" or BACKUPPATH="pathname" attribute to get information about earlier backups. For more information, see Using Backup and Recovery XML Elements. <METADATASERVERBACKUPCONFIGURATION/> Returns the active server backup configuration and the backup schedule. For more information, see Using Backup and Recovery XML Elements. <METADATASERVERRECOVERYMANIFEST/> Lists the metadata repositories, metadata server journal file, and configuration files copied in the last recovery for validating the recovery. For more information, see Using Backup and Recovery XML Elements. <MODELVERSION/> Requests the SAS Metadata Model version number. <OMA email-system-option(s)/> Requests the current value of the specified e-mail system option. The SAS Metadata Server uses the e-mail system to send alert e-mails. For more information, see Requesting Server Invocation Options.
			<OMA journal-statistic(s)/> Returns the specified statistic about the SAS Metadata Server journal file. See Requesting Journaling Statistics for information about the available statistics. <omaconfig-option(s)/> Requests the current value of the specified <OMA> or <RPOSMGR> configuration option, whether it was set in the omaconfig.xml configuration file at startup, or whether it was modified after start-up with the Refresh method. When requesting configuration options, uppercase both the category name and the attribute name in the input XML element. (For example, <OMA JOURNALTYPE=""/> or <RPOSMGR OPTIONS=""/>). The omaconfig.xml file is case sensitive. All other Status input XML elements can be specified in uppercase or lowercase letters. For more information, see Requesting omaconfig.xml Values. <OMA server-process-statistic/> Returns the value of the specified server process statistic. For more information, see Requesting Server Process Statistics. <PLATFORMVERSION/> Requests the SAS Metadata Server version number. <PAUSECOMMENT/> Used with <SERVERSTATE/>, this option returns a user-defined text comment describing why the server is unavailable if the server is in an ADMIN, READONLY, or OFFLINE state. <RPOSMGR omaconfig-option=" "/> Requests the value that is stored for the specified <RPOSMGR> configuration option in the omaconfig.xml file.
			<SCHEDULE EVENT="Backup" WEEKDAYn=""/> Returns the backup times stored in the backup schedule for the specified days. For more information, see Using Backup and Recovery XML Elements. <SCHEDULER PING=" "/> Determines whether the SAS Metadata Server backup scheduler thread is viable by sending a packet and waiting for a response. Possible return values include Alive, TimeOut, Down, or Unconfigured. For more information, see Using Backup and Recovery XML Elements. <SERVERLOCALE/> Requests the server locale that is active for the SAS Metadata Server session. <SERVERSTATE/> Requests information about the SAS Metadata Server's current state. <STATE/> Deprecated. Use <SERVERSTATE/> instead. <VERSION/> Deprecated. Use <MODELVERSION/> or <PLATFORMVERSION/> instead.
outmeta	string	out	Mirrors the content in the INMETA parameter with the exception that return values are filled in.
options	C	in	No options are supported at this time.

Details

Standard Status Elements

The following is a more detailed description of the standard Status XML elements:

Returns the SAS Metadata Model version number in the form X.XX. For example, 12.04. The model version is incremented when there is a change to the SAS Metadata Model or to the repository format used by metadata repositories. The integer part of the version number is the repository format number. When this number is incremented, it indicates that the underlying data structure has changed and a conversion of the repository tables is highly recommended. It is possible for a SAS Metadata Server that was written for one repository format to use repositories that were created with an earlier repository format. However, there will likely be a performance penalty, and some features will not be available.

The decimal part of the version number indicates that a SAS Metadata Model change was made, but there is no need for conversion of the repository tables. A model change includes the addition or modification of metadata types, attributes, or associations.

When the SAS Metadata Server is paused to an ADMIN, READONLY, or OFFLINE state, this option returns a user-defined text comment set by the administrator describing why the server is unavailable. If the SAS Metadata Server is online, it returns an empty string.

Returns the SAS Metadata Server version number in the form X.X.X.X. For example, for a SAS Metadata Server that is running SAS 9.3, the platform version number is 9.3.0.0.

Returns the SAS Metadata Server's current state. Valid values are ONLINE, ADMIN, ADMIN(READONLY), READONLY, RECOVERY, or OFFLINE. No response means that the server is down.

Returns the same information as <SERVERSTATE/>.

This is the default option if the method is issued without options. This option returns values for <MODELVERSION/>, <PLATFORMVERSION/>, <SERVERSTATE/>, <PAUSECOMMENT/>, and <SERVERLOCALE/> in one request.

Returns the same information as <MODELVERSION/>.

Note: The Status method reports the availability of the SAS Metadata Server to client requests. It cannot be used to check the state of specific metadata repositories. If you need to know why a specific metadata repository is not available, check the repository's Access and State values in the SAS Management Console Metadata Manager plug-in, or issue a GetRepositories method that sets the OMI_ALL (1) flag. For more information, see GetRepositories.

Requesting omaconfig.xml Values

The omaconfig.xml file requests changes to the standard SAS Metadata Server configuration. A configuration option is included in this file only to configure a setting that is a departure from the standard configuration, or to provide a value that is required by the standard configuration. The file does not provide all server configuration settings. For information about the options supported in the omaconfig.xml file, see SAS Intelligence Platform: System Administration Guide.

The options in the omaconfig.xml file represent permanent choices for the server’s configuration. That is, the settings are enforced when the metadata server is started. The settings remain enforced until the server is stopped and the omaconfig.xml file is changed. There are a few exceptions. Some options can be changed on a running server with the Refresh method.

The omaconfig.xml file supports configuration options in three categories.

General server control, where each option is specified as an XML attribute of an <OMA> XML element.
Repository manager control, where each option is specified as an XML attribute of an <RPOSMGR> XML element.
Internal authentication control, where each option is specified as an XML attribute of an <InternalAuthenticationPolicy> XML element.

The Status method obtains values for specified <OMA> and <RPOSMGR> attributes. This is only if the attributes for these XML elements exist in the omaconfig.xml file, and if they have been modified with the Refresh method. For information about attributes that can be changed with the Refresh method, see Refresh.

The Status method does not return values for <InternalAuthenticationPolicy> attributes. To determine the settings of <InternalAuthenticationPolicy> attributes, use the GetInternalLoginSitePolicies method. See GetInternalLoginSitePolicies.

If the requested <OMA> or <RPOSMGR> attribute is missing from the omaconfig.xml file, and it has not been modified by the Refresh method, the Status method returns a blank value. A blank value indicates that the option is operating with a standard configuration setting.

When querying omaconfig.xml options, use the case documented for the option in the SAS Intelligence Platform: System Administration Guide. If the case does not match, the Status method returns a blank value.

Requesting Server Invocation Options

In SAS 9.3, the Status method can be used to return the following server invocation options:

LOCALE
e-mail system options for the SAS Metadata Server’s alert notification system

To get the active server LOCALE value, specify <SERVERLOCALE/> in the Status method.

To get the values of e-mail system options, specify:

Returns the authentication protocol for SMTP that is sent by the SAS Metadata Server. Valid values are LOGIN or NONE. The value “LOGIN” means an ID and password are used. The value “NONE” indicates that no authentication protocol is used.

Returns the network address of the enterprise’s SMTP server (for example, mailhost.company.com).

Returns the active e-mail address for the From field of alert e-mail messages that are sent by the SAS Metadata Server.

Returns the logon password that is used with the e-mail address configured in the EMAILID attribute, in encrypted form.

Returns the port number that is used by the SMTP server that is configured in the EMAILHOST attribute.

The Status method returns the current system option values, whether they were set in the sasv9.cfg file or modified with the Refresh method.

Requesting Journaling Statistics

Journaling is a SAS Metadata Server performance feature that makes updates available in memory before they are written to SAS metadata repositories. The updates are stored in a high-speed journal file on disk until they can be transferred to the metadata repositories. In SAS 9.3, a server-based facility uses the transactions stored in the journal file to perform roll-forward recovery.

Journaling statistics enable you to monitor the size, content, and location of the journal file.

To conserve disk space, the SAS 9.3 Metadata Server stores journal entries in a compressed format. XML elements that return journal size in bytes can now report statistics for the compressed journal entries. To get decompressed values, you must include “DECOMP” in the name of the option. An option name that includes “DECOMP” returns the in-memory size before compression. For more information about SAS Metadata Server journaling, see the SAS Intelligence Platform: System Administration Guide.

Although journaling statistics are requested like omaconfig.xml options, they are not documented the same way because, with the exception of <OMA JOURNALPATH=""/>, they do not configure the SAS Metadata Server— they return statistics only. <OMA JOURNALPATH=""/> serves a dual purpose. When specified in the omaconfig.xml file with <OMA JOURNALTYPE="SINGLE"/>, it configures the location of the journal file. When specified in the Status method, it reports the location of the journal file. Because of its usage in the omaconfig.xml file, <OMA JOURNALPATH=""/> must be in all uppercase like other omaconfig.xml options.

Returns the number of bytes of data that are in the journal file that have yet to be applied to metadata repositories. To get the decompressed value, submit <OMA JOURNALDECOMPDATAAVAILABLE=""/>.

Returns a sequence number that indicates the number of add, update, and delete transactions that have been processed since the SAS Metadata Server was started with journaling enabled. The number includes transactions that are still pending in the journal file, and transactions that have been applied to metadata repositories. In SAS 9.3, this sequence number is maintained across server executions.

Returns the total number of bytes of data that have been processed since the journal file was created. This number grows through the life of the journal file. It is not reset when the server is stopped and restarted. To get the decompressed value, submit <OMA JOURNALHISTORICALDECOMPDATA/>.

Returns the largest number of bytes of data that have been held in the journal file before being committed to metadata repositories. This is the maximum value that JOURNALDATAAVAILABLE has ever attained. To get the decompressed value, submit <OMA JOURNALMAXDECOMPDATAAVAILABLE=""/>.

Returns the number of bytes of data in the largest journal entry that has been written to the journal file. This number can grow through the life of the journal file. It is not reset when the server is stopped and restarted. To get the decompressed value, submit <OMA JOURNALMAXDECOMPFILEENTRYSIZE=""/>.

Returns the current location of the journal file.

Returns the number of transactions that are waiting in memory to be applied to metadata repositories on disk. The number of transactions in memory reflect the number of transactions that are in the journal file, unless JOURNALSTATE contains the keywords DOTERM, FORCETERM, or TERMDONE. Under these conditions, it is a good idea to check the server log as the journal file might contain entries that are not in the memory queue.

Returns either the number of bytes of space left in the journal file if the file is a fixed size, or 999999999 if the file is not a fixed size.

Returns the pathname of the directory where the SAS Metadata Server was started.

Returns a keyword indicating the internal status of journal entry processing for troubleshooting. Valid keywords are the following:

Uninitialized

Indicates that journaling is not enabled on the SAS Metadata Server.

IDLE

Indicates that journaling is enabled. However, there are no journal entries being processed.

BUSY

Indicates that journaling is enabled, and the SAS Metadata Server is processing journal entries.

DOTERM

Indicates that the SAS Metadata Server is accepting journal entries. However, the process that applies the updated transactions to repositories on disk will be terminated after the current transaction is processed. It is a good idea to check journal messages in the server log when you receive this keyword.

FORCETERM

Indicates that the SAS Metadata Server is accepting journal entries. However, the process that applies the updated transactions to repositories on disk is in the process of being forcefully terminated, perhaps in the middle of a transaction. It is a good idea to check journal messages in the server log when you receive this keyword.

TERMDONE

Indicates that a DOTERM or FORCETERM was successfully processed. The SAS Metadata Server continues to accept entries in the journal file. However, it is not applying transactions to repositories on disk. It is a good idea to check journal messages in the server log when you receive this keyword.

WAIT_IDLE

Indicates that the SAS Metadata Server is waiting to perform a request (such as changing a repository's properties) that cannot occur until all outstanding journal entries have been applied to repositories on disk. When all pending transactions have been applied, journaling is returned to an IDLE state.

CRASH_RECOVERY

Indicates that the SAS Metadata Server is using journal entries to recover from a server crash.

Using Backup and Recovery XML Elements

The SAS 9.3 Metadata Server supports the ability to back up and recover itself. Server backups are performed in a dedicated server backup thread. As a result, backups do not interrupt the regular operation of the metadata server. Backups are controlled by a scheduler process that runs in a dedicated scheduler thread. Server recovery processes are integrated with the metadata server journal to support roll-forward recovery up to a specified point in time since the restored backup image. The SAS 9.3 Metadata Server is installed with a default backup configuration and backup schedule.

The SAS Metadata Server uses four system files in the SASMeta/MetadataServer directory that manage backup and recovery processes.

MetadataServerBackupConfiguration.xml

contains the backup configuration and backup schedule.

MetadataServerBackupHistory.xml

contains a history of backup and recovery activity.

MetadataServerBackupManifest.xml

contains a record of the repositories and files copied in a backup. This file is created for each backup in the backup's directory,and it can be used to validate the backup. A copy of this file for the most recent backup is also kept in the server directory.

MetadataServerRecoveryManifest.xml

contains a record of the repositories and files copied in a recovery. This file can be used to validate the recovery. The facility overwrites the last file with the new file each time a recovery is performed.

CAUTION:

These four system files should never be opened directly.

The <METADATASERVERBACKUPCONFIGURATION/>, <METADATASERVERBACKUPHISTORY/>, <METADATASERVERBACKUPMANIFEST/>, and <METADATASERVERRECOVERYMANIFEST/> XML elements enable clients to list the contents of the files.

The <METADATASERVERBACKUPCONFIGURATION/> XML element lists the content of the MetadataServerBackupConfiguration.xml file. The <METADATASERVERBACKUPHISTORY/> XML element lists the content of the MetadataServerBackupHistory.xml file. The <METADATASERVERBACKUPMANIFEST/> XML element returns the MetadataServerBackupManifest.xml file from the latest backup.

To get the MetadataServerBackupManifest.xml file from an earlier backup, include the BACKUPNAME="name" or BACKUPPATH="pathname" attribute in <METADATASERVERBACKUPMANIFEST/>. BACKUPNAME="name" gets the file for the backup of the specified name from the active backup location. BACKUPPATH="pathname" gets the file for a backup that is stored in a location other than the active backup location. Pathnames are considered to be relative to the SASMeta/MetadataServer directory. To get a backup from another backup location, specify an absolute pathname.

To enable clients to retrieve specific records from the history and manifest files, the XML elements requesting these files support limited XPATH search syntax specified in an XPATH="" attribute. Two syntax elements are supported: XPATH [POSITION()=LAST()] and XPATH [@ATTRIBUTE='value']. The XPATH [POSITION()=LAST()] syntax can be specified in a <METADATASERVERBACKUPHISTORY/> request to get the last backup in the MetadataServerBackupHistory.xml file.

<MetadataServerBackupHistory XPath="MetadataServerBackupManifest/Backups/
Backup[POSITION()=LAST()]" />

The XPATH [@ATTRIBUTE='value'] syntax can return information about specific files in a backup or recovery. For example, the following request gets information about the adminUsers.txt file from the MetadataServerBackupManifest.xml file:

<MetadataServerBackupManifest XPath="MetadataServerBackupManifest/Backups/
Backup/ConfigurationFiles/File[@Name='adminUsers.txt'" />

You must familiarize yourself with the structure of the history and manifest files to build XPATH queries.

The <BACKUPCONFIGURATION/> and <SCHEDULE Event="Backup" WeekDayn=""/> XML elements get only backup configuration and only schedule information from the MetadataServerBackupConfiguration.xml file, respectively. The facility has a weekly backup schedule that specifies backup times in WeekDayn="timevalue" attributes, where n represents a day of the week. WeekDay1 is Sunday and WeekDay7 is Saturday. To get the backup schedule for a particular day, specify the WeekDayn="" attribute with an appropriate number. The facility returns four-digit time values based on a 24-hour clock in the time zone in which the server is running. If more than one backup is scheduled in a day, the time values are separated by semicolons. An “R” appended to a time value indicates that a REORG is scheduled to be performed with the backup.

<SCHEDULER PING=""/> checks the health of the scheduler thread. <BACKUP BYTESTOCOPY="" BYTESCOPIED="" ISRUNNING=""/> tracks backup progress and determines the number of bytes of data that were copied in a backup.

Requesting Server Process Statistics

Beginning in SAS 9.3, the following XML elements return SAS Metadata Server process statistics. The metrics are useful for multi-user performance testing.

returns the total seconds consumed by the metadata server on non-kernel (user) processing.

returns the total seconds consumed by the server on kernel (system) processing.

returns the server's current time as a SAS datetime value (the number of seconds since January 1, 1960).

returns the amount of memory currently being used by the server, in bytes.

returns the highest amount of memory used by the server, in bytes.

returns the number of active threads on the server.

returns the highest number of threads used by the server.

returns the total number of bytes read and written by the server.

Examples

Standard Interface Example

The following example shows how the Status method is issued in the standard interface:

<! -- Default values returned by Status method in SAS 9.3  -->
inmeta=' ';
outmeta=' ';
options=' ';

rc=serverObject.Status(inmeta,outmeta,options);

The Status method is issued without specifying options in the INMETA parameter to show the default behavior of the method. The following is the output from the request:

<ModelVersion>12.04</ModelVersion>
<PlatformVersion>9.3.0.0</PlatformVersion>
<ServerState>ONLINE</ServerState>
<PauseComment/>
<ServerLocale>en_US</ServerLocale>

DoRequest Examples

The following examples are formatted for the INMETADATA parameter of the DoRequest interface.

This is the same method call that was issued in the standard interface example.

<!-- Default values returned by the Status method  -->
<Status>
<Metadata/>
<Options/>
</Status>

The Status method call requests omaconfig.xml values and <SERVERLOCALE/>:

<!-- Get omaconfig.xml values -->
<Status>
<Metadata>
<OMA MAXACTIVETHREADS=""/>
<OMA JOURNALTYPE=""/>
<OMA ALERTEMAIL=""/>
<RPOSMGR
LIBREF=""
ENGINE=""
PATH=""
OPTIONS=""/>
<SERVERLOCALE/>
</Metadata>
<Options/>
</Status>

This Status method call requests the value of the omaconfig.xml <OMA JOURNALTYPE="SINGLE | ROLL_FORWARD | NONE"/> server configuration option and journaling statistics:

<!-- Get journaling statistics-->

<Status>
<Metadata>
<OMA JOURNALTYPE=""
     JOURNALPATH="" 
     JOURNALSTATE=""
     JOURNALQUEUELENGTH=""
     JOURNALDATAAVAILABLE=""
     JOURNALSPACEAVAILABLE=""
     JOURNALENTRYCOUNTER=""/>
</Metadata>
<Options/>
</Status>

The value returned for the JOURNALTYPE option indicates whether journaling is enabled on the server and, if so, the type of journaling being performed. When the JOURNALTYPE value is “ROLL_FORWARD”, the server controls the location of the journal file reported in the JOURNALPATH attribute. (“ROLL_FORWARD” is the default value in SAS 9.3 because roll-forward recovery of the server is required.) When the JOURNALTYPE value is “SINGLE”, you can control the location of the journal file with the JOURNALPATH option in the omaconfig.xml file. The other attributes return statistics about journaling if journaling is enabled.

The following Status request gets the backup parameters and backup schedule that are active on the SAS Metadata Server:

<!-- Get server backup configuration -->
<Status>
  <Metadata>
    <MetadataServerBackupConfiguration/>
  </Metadata>
  <Options/>
</Status>

The following Status request gets the backup schedule for Tuesday:

<!-- Get the Tuesday backup schedule -->
<Status>
  <Metadata>
    <Schedule Event="Backup" Weekday3=""/>
  </Metadata>
  <Options/>
</Status>

Related Methods

GetInternalLoginSitePolicies