Server Control (IServer Interface)

Status

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

Category: Server control methods

Syntax

rc=Status(inmeta,outmeta,options);

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 it did, RC=1 means it did not.
inmeta	string	in	An XML element that requests additional information to be returned from the SAS Metadata Server. One or more elements can be specified. If no elements are specified, the Status method returns <MODELVERSION/>, <PLATFORMVERSION/>, <SERVERSTATE/>, <PAUSECOMMENT/>, and <SERVERLOCALE/>, by default. <MODELVERSION/> Requests the SAS Metadata Model version number. <OMA AttributeName=" "/> Requests the value that is active for the specified <OMA> attribute in the server's default configuration or in the omaconfig.xml file. <OMA JournalStatistic=" "/> Returns the specified journal statistic about the SAS Metadata Server journal file. See Requesting Journaling Statistics for information about the available 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 or OFFLINE state. <RPOSMGR AttributeName=" "/> Requests the value that is active for the specified <RPOSMGR> attribute in the server's default configuration or in the omaconfig.xml file. <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 in SAS 9.2. Use <SERVERSTATE/> instead. <VERSION/> Deprecated in SAS 9.1.3, Service Pack 3. Use <MODELVERSION/> and <PLATFORMVERSION/> instead.
outmeta	string	out	Mirrors the INMETA parameter with the exception that return values are filled in.
options	C	in	No options are supported at this time.

Details

Any user who has access to the SAS Metadata Server can use the Status method.

The INMETA parameter is a string containing one or more XML elements that requests information. If a null string is passed, the Status method returns values for <MODELVERSION/>, <PLATFORMVERSION/>, <SERVERSTATE/>, <PAUSECOMMENT/>, and <SERVERLOCALE/>, by default. These options are considered the standard elements.

The other elements in the INMETA parameter are optional and can be used to return the following information:

the values of specified server configuration options that are set in the omaconfig.xml file.
journaling statistics for installations that have journaling enabled. In SAS 9.2, the default server configuration has journaling enabled.

For more information, see Requesting omaconfig.xml Values and Requesting Journaling Statistics.

Standard Status Elements

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

<MODELVERSION/>

Returns the SAS Metadata Model version number in the form X.XX. For example, 11.03. 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, as it was between SAS 9.1.3 and SAS 9.2, 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.

<PAUSECOMMENT/>

When the SAS Metadata Server is paused to an ADMIN 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.

<PLATFORMVERSION/>

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.2, the platform version number is 9.2.0.0. For a SAS Metadata Server that is still running SAS 9.1.3, Service Pack 4, the platform version number is 9.1.3.4.

<SERVERSTATE/>

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

<STATE/>

Returns the same information as <SERVERSTATE/>.

<STATUS/>

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.

<VERSION/>

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. [cautionend]

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 a definitive listing of all server configuration settings.

The omaconfig.xml file supports options in three categories.

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

The Status method obtains values for specified <OMA> and <RPOSMGR> elements, if attributes for these elements exist in the omaconfig.xml file. If the requested attribute is missing from the omaconfig.xml file, the Status method returns a blank value. A blank value indicates that the option is operating with a standard configuration setting.

To request an attribute value, submit an XML element of the appropriate category (<OMA> or <RPOSMGR>) that specifies the name of the attribute whose value you'd like to read in the INMETA parameter. To determine the attribute names available in each category and learn their standard configuration settings, see "Configuration Files: Reference for omaconfig.xml" in the SAS Intelligence Platform: System Administration Guide. Capitalize both the category name and the attribute name in the input XML element. The Status method is case sensitive.

To determine the settings of <InternalAuthenticationPolicy> options, use the GetInternalLoginSitePolicies method. For more information, see GetInternalLoginSitePolicies.

Requesting Server Invocation Options

The only server invocation option that is returned by the Status method is LOCALE, which specifies the server language encoding for the server session. To get the active server LOCALE value, specify <SERVERLOCALE/> in the Status method.

Requesting Journaling Statistics

Journaling is a SAS Metadata Server performance feature that makes updates available in memory before they are written to disk. For more information about SAS Metadata Server journaling, see the SAS Intelligence Platform: System Administration Guide.

<OMA JOURNALDATAAVAILABLE=""/>

Returns the number of bytes of data that are in the journal file in memory and have yet to be applied to metadata repositories on disk.

<OMA JOURNALENTRYCOUNTER=""/>

Returns a sequence number that indicates the number of transactions that have been processed since the SAS Metadata Server was started with journaling enabled. The number includes transactions that are still in the journal file, and transactions that have been applied to metadata repositories on disk. This number is reset when the server is paused to an OFFLINE state and then resumed, and when the server is stopped and then restarted.

<OMA JOURNALHISTORICALDATA=""/>

Returns the number of transactions that have been processed to the disk data sets since the SAS Metadata Server was started.

<OMA JOURNALMAXDATAAVAILABLE=""/>

Returns the number of bytes of data that has been written to the journal file. This number grows through the life of the journal file. It is not reset when the server is stopped and then restarted.

<OMA JOURNALQUEUELENGTH=""/>

Returns the number of transactions in the journal file that are waiting to be applied to metadata repositories on disk.

<OMA JOURNALSPACEAVAILABLE=""/>

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.

<OMA SERVERSTARTPATH=""/>

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

<OMA JOURNALSTATE=""/>

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.

Although these journaling statistics are requested like omaconfig.xml options, they are not documented the same way because they do not configure the SAS Metadata Server-- they return statistics only.

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.2  --->
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>11.03</ModelVersion>
<PlatformVersion>9.2.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 in SAs 9.2 --->
<Status>
<Metadata/>
<Options/>
</Status>

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

<!-- Get omaconfig.xml values -->

<Status>
<Metadata>
<OMA MAXACTIVETHREADS=""/>
<OMA JOURNALPATH=""/>
<OMA ALERTEMAIL=""/>
<RPOSMGR
LIBREF=""
ENGINE=""
PATH=""
OPTIONS=""/>
<SERVERLOCALE/>
</Metadata>
<Options/>
</Status>

This Status method call requests the value of the omaconfig.xml <OMA JOURNALPATH="filename"/> server configuration option and journaling statistics:

<!-- Get journaling statistics-->

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

The value returned for the JOURNALPATH attribute, which can be an absolute or relative pathname or a blank string, indicates whether journaling is enabled on the SAS Metadata Server. The other attributes return statistics about journaling, if journaling is enabled.

Related Methods

GetInternalLoginSitePolicies

Top of Page