Refresh

Short Description

Changes certain SAS Metadata Server invocation and configuration options on a running server. This method can also be used to quickly recover memory on the server.

Syntax

rc=Refresh(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.
options	C	in	<ARM system-option(s)/> Invokes specified ARM logging system options. For more information, see ARM Configuration Options. <BACKUP options /> Invokes an ad hoc SAS Metadata Server backup. For more information, see Server Backup and Recovery Options. <BACKUPCONFIGURATION attribute(s)/> Sets or modifies the specified server backup configuration attributes in the MetadataServerBackupConfiguration.xml file. For more information, see Server Backup and Recovery Options. <OMA ALERTEMAIL="email-address"/> Sets the e-mail address to which the SAS Metadata Server will send an e-mail message in the event of a metadata erver backup error, a metadata server recovery error, or an error that prevents the repository data sets from being updated from the journal. To specify more than one e-mail address, enclose each address in single quotation marks, place a blank space between each address, and enclose the list in parentheses. For example: "('Bill@mycompany.com' 'Susan@mycompany.com')" <OMA ALERTEMAILTEST= “text”/> Sends a test e-mail message to the addresses configured in the SAS Metadata Server’s omaconfig.xml file, specifically in the <OMA ALERTEMAIL="email-address"/> option. The e-mail recipients are displayed on the General tab of the active server's Properties window in SAS Management Console. Or, e-mail recipients can be listed with the Status method. <OMA email-system-option(s)/> Changes the values of specified e-mail system options on a running SAS Metadata Server. For more information, see E-Mail System Options.
			<OMA JOURNALPATH="filename"/> Specifies to stop writing journal entries to the journal file in the current location and resume writing journal entries in a new file in the specified location. In SAS 9.3, this option is valid only when the metadata server is configured with <OMA JOURNALTYPE="SINGLE"/> in the omaconfig.xml file. If the server is configured with any other journal type value, this option returns an error.
			<RECOVER options/> Restores the SAS Metadata Server from a specified server backup and optionally performs a roll-forward recovery from the metadata server journal file. For more information, see Server Backup and Recovery Options. <REPOSITORY Id="repository-identifier"/> Specifies to close and reopen the specified metadata repository to recover memory. <RPOSMGR ACCESS="ONLINE"/> Specifies to resume the SAS Repository Manager to an ONLINE state. When the SAS Repository Manager is resumed, metadata repositories are returned to their registered Access value. <SCHEDULE EVENT="Backup" WEEKDAYn="time"/> Sets or modifies the server backup schedule in the MetadataServerBackupConfiguration.xml file. For more information, see Server Backup and Recovery Options. <SCHEDULER/> Specifies one of two XML subelements to manage the server backup scheduler thread. Valid subelements are <REBUILD/> or <RESTART/>. For more information, see Server Backup and Recovery Options. <SERVER/> Specifies to close and reopen all of the metadata repositories that are managed by the SAS Metadata Server to recover memory.

Details

General Operation

A user must have administrative user status on the SAS Metadata Server to issue the Refresh method.

Issuing the Refresh method without options has no effect.

When executed with the <SERVER/> element, the Refresh method pauses the SAS Metadata Server to an OFFLINE state, and then resumes it to an ONLINE state, in one step. This process unloads all metadata repositories that are managed by the SAS Metadata Server and the SAS Repository Manager from memory, and closes all repository containers on disk. Memory on the SAS Metadata Server host is quickly recovered. The repositories remain in their current Access state. Closed containers are reopened as needed in response to subsequent metadata queries and updates.

The <SERVER/> element does not have any attributes or parameters. It is specified in the OPTIONS parameter as follows:

<SERVER/>

The <REPOSITORY Id="repository-identifier"/> element unloads the specified metadata repository (or metadata repositories) from memory and closes their containers on disk, recovering memory on the SAS Metadata Server host. The specified repositories remain in their current Access state. Closed containers are reopened as needed in response to metadata queries and updates. The <REPOSITORY/> element is specified as follows:

<REPOSITORY Id="Reposid|REPOSMGR|ALL"/>

REPOSID

Specifies the unique 8-character or two-part 17-character metadata identifier of a metadata repository. Multiple repositories can be refreshed at once by stacking <REPOSITORY/> elements in the OPTIONS parameter.

Note: The foundation repository should not be refreshed without also refreshing all metadata repositories that depend on it.

REPOSMGR

specifies the SAS Repository Manager.

ALL

Includes all metadata repositories, including the SAS Repository Manager. ALL is the default value if <REPOSITORY/> is specified without an Id value and has the same effect as specifying the <SERVER/> element.

Issuing the Refresh method with one of the other OPTIONS elements, except <OMA ALERTEMAILTEST= “text”/>, reconfigures a feature on the running SAS Metadata Server. There are four categories of optional configuration elements: e-mail system options, ARM system options, a journal option, and server backup and recovery options.

The <OMA ALERTEMAILTEST= “text”/> XML element is provided to test the metadata server's alert e-mail notification system. If the test e-mail is not received, you can use <OMA e-mail-system-option(s)/> to change the e-mail server’s configuration while the metadata server is running, and test again until the test succeeds. You can use <OMA ALERTEMAIL="email-address"/> to change the alert e-mail recipients. Refresh changes the option settings for the duration of the server session. To permanently change e-mail system options for the alert e-mail server, you must modify the sasv9.cfg file. To permanently change alert e-mail recipients, you must modify the omaconfig.xml file. You must stop the metadata server in order to modify these files.

The SAS Metadata Server must refresh repositories when there is no other activity on the server, so it automatically delays other client requests until the Refresh method completes. This might have a small effect on server performance.

None of the configuration options affect memory size.

E-Mail System Options

The <OMA e-mail-system-option(s)/> include:

Changes the authentication protocol for SMTP e-mail that is sent by the SAS Metadata Server. When you specify the value “LOGIN”, you also need to specify EMAILID and EMAILPW. The value “NONE” specifies that no authentication protocol is used.

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

Changes the e-mail address for the From field of alert e-mail messages that are sent by the SAS Metadata Server. The e-mail address can be entered in either of the following forms:

"server-name<user-account@domain>"
"<user-account@domain>"

Specifies the logon password to be used with the e-mail address that you specified for the EMAILID option. The password should be encoded with PROC PWENCODE. We recommend that you use SAS02 as the minimum encryption level. SAS02 is the standard SAS proprietary encryption level that is available with PROC PWENCODE. In order to specify a higher encryption level, you must have SAS/SECURE software. For more information about PROC PWENCODE, see the Base SAS Procedures Guide.

Changes the port number that is used by the SMTP server that you specified for the EMAILHOST option.

To get the current values of the e-mail system options, use the Status method. For more information, see Status. For more information about the metadata server’s alert e-mail notification system, see the SAS Intelligence Platform: System Administration Guide.

ARM Configuration Options

Is one or more ARM system options that are specified as follows:

<ARM ARMSUBSYS="(ARM_NONE|ARM_OMA)" ARMLOC="fileref|filename"/>

The ARMSUBSYS system option enables or disables ARM logging on the server. Specify "(ARM_OMA)" to enable ARM logging. Specify “(ARM_NONE)” to disable ARM logging. ARM logging is disabled by default.

The ARMLOC system option specifies a location for the log. ARMLOC should be specified with ARMSUBSYS when you enable ARM logging. If ARM logging is already enabled, specifying just ARMLOC=“filename” writes the ARM log to a new location. Absolute and relative pathnames are read as different locations. For more information about ARM logging, see “Using the ARM_OMA Subsystem” in the SAS Intelligence Platform: System Administration Guide.

Server Backup and Recovery Options

The following options set or modify the server backup configuration and server backup schedule for the server-based backup and recovery facility, and execute adhoc backups and recoveries. An option is also provided to maintain the scheduler thread.

Invokes an ad hoc server backup to the backup location indicated in the MetadataServerBackupConfiguration.xml file. The backup is named with a datetime stamp in a modified ISO-8601 format (server-local datetime value followed by the GMT offset). The <BACKUP/> element supports two optional attributes:

COMMENT= “text”

Specifies a text string of an unlimited length to describe the reason for the ad hoc backup. The text string is recorded in the backup history.

REORG="Y|N"

Specifies whether repository data sets should be rebuilt to remove unused disk space. The default value is “N” (No). Use of this option in ad hoc backups is discouraged as the REORG process pauses and resumes repositories, which interrupts the regular operation of the metadata server.

Sets or modifies the value of a specified server backup parameter in the MetadataServerBackupConfiguration.xml file. The parameters are:

BACKUPLOCATION="directory"

Specifies backups will be stored in a directory of the specified name in the SASMeta/MetadataServer directory of your SAS configuration. The default backup directory is named Backups. If the specified directory does not exist, the metadata server will create it for you. To create the directory in a location other than SASMeta/MetadataServer or on a different drive, specify an absolute pathname that is meaningful to the computer that hosts the SAS 9.3 Metadata Server. The server will create one directory for backups; if a pathname is specified, the other directory levels must already exist.

RUNSCHEDULEDBACKUPS="Y|N"

Controls the scheduler thread. A value of “Y” activates scheduled backups; a value of “N” turns them off.

DAYSTORETAINBACKUPS="number"

Specifies the number of days to keep backups before they are deleted from the SAS Metadata Server host. The default value is “7”. To never remove any backups, specify “0” in this attribute. Specifying a value of 0 is not recommended as it can cause disk space issues.

Restores SAS metadata repositories using the backup specified in a BACKUPNAME="name" or a BACKUPPATH="pathname" attribute with the options indicated in optional attributes. The specified backup is recovered to the current metadata server directory. If the server path was different when the backup was made, the repository pathnames in the backup are changed to relative pathnames to enable the server to function in the new location.

BACKUPNAME or BACKUPATH are required parameters.

BACKUPNAME="name"

Specifies the name of a backup to use to recover the server. The backup is assumed to be located in the backup location indicated in the MetadataServerBackupConfiguration.xml file. To use a backup from a different location to recover the server, either use the BACKUPPATH attribute instead of BACKUPNAME, or specify the BACKUPLOCATION attribute with the BACKUPNAME attribute.

BACKUPLOCATION="directory"

Specifies the name of the directory that contains the backup specified in BACKUPNAME.

BACKUPPATH="pathname"

Specifies the full or relative pathname to a backup. Relative pathnames are mapped to the SASMeta/MetadataServer directory.

Optional parameters include:

COMMENT="text"

Specifies a character string of unlimited length that contains an explanation for the recovery. The text is recorded in the backup history.

PAUSECOMMENT="text"

Specifies a character string of unlimited length that will be displayed as a recovery notification to clients.

IGNOREVERIFY= “Y | N”

Specifies whether to perform a validation process to determine if the content of the backup matches the record of the backup in the METADATASERVERBACKUPMANIFEST.xml file, and abort the recovery if it does not match. The value “N” instructs the server to perform the validation. This is the recommended setting. The value “Y” instructs the metadata server to perform the recovery, skipping the validation.

CAUTION:

You should evaluate your backup very carefully before you set IGNOREVERIFY="Y".

If the backup is missing a critical component, like the repository manager (A0000001) or a repository, your server might not start after recovery.

INCLUDEALLCONFIGFILES= “Y|N”

Specifies whether to replace all configuration files in the server directory with the configuration files present in the directory when the backup was taken.

CAUTION:

When INCLUDEALLCONFIGFILES="Y", all files in the server directory will be deleted and replaced with the configuration files in the backup.

Any files added to the directory since the backup will be lost.

ROLL_FORWARD= "blank|_ALL_|datetime"

Specifies whether the metadata server journal should be used to recover metadata server transactions that were recorded beyond those recovered in the restored image, and whether to recover all transactions or only transactions up to a specified point from the journal. Omission of this parameter, or specifying the parameter with a blank value, specifies not to recover transactions from the journal.

_ALL_	specifies to recover all transactions in the journal.
Datetime	specifies to recover transactions up to the specified date and time. The ROLL_FORWARD argument requires input in GMT time.

Sets or modifies the server backup schedule. The server backup schedule is stored in the MetadataServerBackupConfiguration.xml.

EVENT= “Backup”

specifies the event to schedule. “Backup” is the valid value.

WEEKDAYn= “timevalue

The server backup facility supports daily backups, specified on a weekly schedule where the attribute Weekday1="timevalue" is Sunday and the attribute Weekday7="timevalue" is the following Saturday and appropriately numbered Weekdayn="timevalue" attributes represent the other days of the week. Backup times are specified using four-digit time values indicating hours and minutes based on a 24-hour clock in server-local time; for example, 0100 is 1 a.m; 1300 is 1p.m. To schedule a backup, specify the appropriate Weekdayn="timevalue" attribute with a time value. To schedule more than one backup in a day, specify multiple time values and separate them with semicolons.

is optional and requests a REORG operation. The REORG option instructs the metadata server to rebuild repositories to remove unused disk space. It is a resource-intensive operation that pauses the server, so should be used sparingly. It is recommended that a REORG be performed no more than once a week.

The <SCHEDULER> element does not change the configuration of the SAS Metadata Server or server backups. The scheduler thread runs continuously from the time the SAS 9.3 Metadata Server is started and buffers the schedule in 48-hour increments. Specifying <SCHEDULER> XML element with the <REBUILD/> subelement forces the scheduler thread to rebuild its in-memory linked list of events. Specifying <SCHEDULER> with the <RESTART/> subelement causes the current scheduler thread to stop and starts a new one.

Examples

The following example shows how ARM_OMA logging is enabled:

options='<ARM armbsubsys="(ARM_OMA)" armloc="myARM.log"/>';
rc=serverObject.Refresh(options);

The following example shows how ARM_OMA logging is disabled:

options='<ARM armbsubsys="(ARM_NONE)"/>';
rc=serverObject.Refresh(options);

The following example shows how to pause and resume a metadata repository to recover memory:

options='<Repository Id="A5H9YT45"/> ';
rc=serverObject.Refresh(options);

The following example shows how to execute an ad hoc server backup to the default backup location:

options='<Backup Comment="Adhoc backup started by the backup.sas job."/>';
rc=serverObject.Refresh(options);

The following example requests a server restore with roll-forward recovery.

options="<Recover BackupPath='Backups/2011-06-01T11_03_03-04_00' 
 IncludeAllConfigFiles='N' RollForward='01jun2011:19:00:00' 
 PauseComment='The metadata server is being recovered.' 
 Comment='Recovery from 2011-06-01T11_03_03-04_00'/>";
rc=serverObject.Refresh(options);

The following example shows how to modify the server backup schedule:

options='<Schedule Event="Backup" Weekday1="0010;1700" 
Weekday2="0010R;1700" Weekday3="0010;1500" Weekday4="0010;1500" Weekday5="0010;1700" 
Weekday6="0010;1700" Weekday7="0010"/>'
rc=serverObject.Refresh(options);