Optional Arguments

NOAUTOPAUSE

NOAUTOPAUSE is required for the DELETE, EMPTY, and UNREGISTER actions. It is required when the REFRESH action is specified with the <BACKUPCONFIGURATION attribute(s)/>, <SCHEDULE Event="BACKUP" WEEKDAYn="timevalueR"/>, <BACKUP attributes/>, <RECOVER BACKUPNAME="name" | BACKUPPATH="pathname" options/> and <SCHEDULER/> XML elements in the OPTIONS= parameter. It is recommended with the <OMA ALERTEMAILTEST="text"/> option. NOAUTOPAUSE omits the automatic pause and resume of the metadata server when PROC METAOPERATE passes an action to the metadata server. Without NOAUTOPAUSE, all repositories experience the implicit pause and resume whenever an action is passed to the server. This can be unwanted because it makes all repositories temporarily unavailable.

OPTIONS="XML-string"

specifies a quoted string that contains one or more XML elements. Some of the XML elements specify additional parameters for the actions. The OPTIONS= argument is required for some actions.

Note: To ensure that the XML string is parsed correctly by the metadata server, you must indicate that quotation marks within the XML element are characters. You can nest single and double quotation marks, or double and double double quotation marks as follows: options='<ARM ARMSUBSYS="(ARM_OMA)" ARMLOC="myfileref"/>' options="<ARM ARMSUBSYS=""(ARM_OMA)"" ARMLOC=""myfileref""/>"

The XML elements include the following:

<ARM parameter-name="value"/>

is one or more <ARM/> XML elements that specify system options to enable or disable ARM logging. REFRESH is the most appropriate action to specify the <ARM/> XML element, but PAUSE and RESUME actions can specify it. If the metadata server is refreshed or stopped and started, ARM parameters return to the values in the configuration file. For more information, see Submitting ACTION=REFRESH with ARM Loggingand the SAS Intelligence Platform: System Administration Guide, as well as the ARMSUBSYS= and ARMLOC= system options in SAS Interface to Application Response Measurement (ARM): Reference. An <ARM/> element can include the following parameters:

ARMSUBSYS="(ARM_NONE | ARM_OMA)"

enables and disables ARM logging.

ARMLOC="fileref | filename"

specifies a location to which to write the ARM log. If ARM logging is already enabled, specifying ARMLOC= writes the ARM log to a new location. Relative and absolute pathnames are read as different locations.

<BACKUP attributes/>

supported with the REFRESH action, invokes an ad hoc backup of the metadata server to the location specified in the server’s backup configuration. The backup is named with a modified date-and-time stamp in ISO 8601 format. For more information, see Using Backup and Recover XML Elements.

Optional attributes are the following:

COMMENT="text"

accepts a user-specified text string of unlimited length to describe the reason for the ad hoc backup. This comment is recorded as part of the backup history. The backup history is visible in the Server Backup node of the SAS Management Console Metadata Manager, or it can be requested with PROC METADATA. For more information, see METADATA Procedure.

REORG="Y | N"

specifies whether repository data sets should be rebuilt to release unused disk space after the backup. The default value is N (No).

CAUTION:

The REORG option is not recommended for ad hoc backups because it interrupts the operation of the metadata server.

For more information, see <SCHEDULE EVENT="Backup" WEEKDAYn="timeR"/>.

<BACKUPCONFIGURATION attribute(s)/>

supported with the REFRESH action, modifies the value of the specified backup configuration attribute. Backup configuration attributes include:

BackupLocation="directory"

specifies the directory in which to write the metadata server backups. The default location is a Backups subdirectory of the SASMeta/MetadataServer directory of your SAS 9.3 configuration. To create the directory in a location other than MetadataServer or on a different drive, specify an absolute pathname that is meaningful to the computer that hosts the metadata server. If the specified directory does not exist, the metadata server will create it for you.

RunScheduledBackups="Y | N"

controls the backup scheduler. A value of “Y” enables scheduled backups. A value of “N” disables them.

DaysToRetainBackups="number"

specifies the number of days to keep backups before they are deleted from the backup location. The default value is “7”. To never remove any backups, specify “0” in this attribute. A value of “0” is not advisable except as a temporary setting.

<FORCE/>

supported with the PAUSE or RESUME actions, regains control of the metadata server during the recovery process in the event that the recovery process stops responding. When used with RESUME, <FORCE/> returns the server to an online state, where it is available to clients. When used with PAUSE, you have the option to specify <SERVER STATE="ADMIN | OFFLINE | READONLY"/> to return the server to the ADMIN state. In the ADMIN state, you can examine the server for problems before making it available to clients.

<OMA ALERTEMAILTEST="text"/>

supported with the REFRESH action, sends a test alert e-mail message to the address configured in the <OMA ALERTEMAIL="email-address"/> option in the omaconfig.xml configuration file. The configured recipients can be viewed on the General tab of the active server’s Properties window in SAS Management Console. The NOAUTOPAUSE argument is recommended. For more information, see Submitting ACTION=REFRESH with the Alert E-mail Test Option.

<OMA JOURNALPATH="filename"/>

supported with the REFRESH action, stops writing journal entries to the metadata server journal file in the current location, and resumes writing journal entries in a new journal file in the specified physical location. This option is valid only when the metadata server is configured with <OMA JOURNALTYPE="SINGLE"/> in the omaconfig.xml configuration file. The default configuration setting is <OMA JOURNALTYPE="ROLL_FORWARD"/>, which supports roll-forward recovery of the server.

<PAUSECOMMENT>text</PAUSECOMMENT>

supported with the PAUSE action, enables you to submit free-form text (for example, details about the pause). Quotation marks are optional around the text. For more information, see Submitting ACTION=PAUSE with a Pause Comment. When you submit the RESUME action, the text in <PauseComment> is cleared.

<RECOVER BACKUPNAME="name" | BACKUPPATH="pathname" options/>

supported with the REFRESH action, recovers the metadata server from the backup specified in the BACKUPNAME="name" or BACKUPPATH="pathname" attribute with the specified options.

BACKUPNAME="name"

specifies the name of a backup. Server backups are named with a modified date-and-time stamp. For information about backup names, see Using Backup and Recover XML Elements. The server looks for backups in the backup location specified in the current configuration. To use a backup from a different directory, either use the BACKUPPATH= attribute instead of BACKUPNAME=, or specify the BACKUPLOCATION= attribute with the BACKUPNAME= attribute. The default backup location is the Backups subdirectory of the SASMeta/MetadataServer configuration directory.

BACKUPPATH="pathname"

specifies the absolute pathname to the backup. This option is useful when the backup is located in a different directory or drive from the backup location specified in the current configuration.

Optional recovery attributes are as follows:

BACKUPLOCATION="directory"

specifies the name of the directory that contains the backup specified in the BACKUPNAME= attribute, if the directory differs from the backup directory specified in the current configuration. The name that you specify is considered to be relative to the SASMeta/MetadataServer directory.

COMMENT="text"

specifies a user-defined text string to record an explanation for the recovery. The text string is displayed in the backup history.

PAUSECOMMENT="text"

specifies a user-defined text string that will be displayed as a recovery notification to clients.

INCLUDEALLCONFIGFILES=" Y | N"

specifies whether to replace configuration files in the server directory with the configuration files that are in the directory when the backup occurs. The default value is N (No).

CAUTION:

When INCLUDEALLCONFIGFILES=" Y", any recent changes to the omaconfig.xml configuration file will be lost, as will any files that were added to the configuration directory after the backup.

The recovery overwrites all files in the SASMeta/MetadataServer directory, except the backup history, backup configuration, and manifests, and replaces them with the configuration files in the backup.

ROLLFORWARD="blank | _ALL_ | datetime"

specifies whether the metadata server journal should be used to apply changes that were made to the server after the backup was taken, and whether to recover all changes from the journal or only changes up to a specified point in time.

Omitting this attribute, or specifying it with a blank value specifies not to recover changes from the journal.

_ALL_

recovers all changes from the journal.

datetime

recovers changes from the journal up to a specified point in time. The metadata server log displays changes in server local time. The ROLLFORWARD= attribute requires input in GMT time. See Using Backup and Recover XML Elements for information to convert server local time values to GMT time.

<SCHEDULE EVENT="Backup" WEEKDAYn="time<R>"/>

supported with the REFRESH action, modifies the server backup schedule.

EVENT="Backup"

specifies the event that will be scheduled. The valid value is "Backup". The Event= attribute is required.

WEEKDAYn="time”

specifies the backup schedule. The metadata server supports daily backups, specified in a weekly schedule where the attribute WeekDay1= is Sunday, the attribute WeekDay7= is Saturday, and appropriately numbered WeekDayn= attributes represent the other days of the week. Backup times are specified in four-digit values based on a 24-hour clock. For example: 0100 is 1 a.m.; 1300 is 1 p.m. The <SCHEDULE EVENT="Backup"/> option accepts input in server local time, and applies values in server local time. The default backup schedule specifies daily backups at 1 a.m. To change the schedule, specify the appropriate WeekDayn= attribute with the backup time. The new time overwrites the old time. To schedule more than one backup in a day, separate the time values with semicolons. For example, “0100; 1300”. To remove all backups from a day, specify an empty string.

R

specifies to perform a REORG with a backup. REORG releases unused disk space from repository data sets after a backup. The operation is necessary for repository maintenance, but is time-intensive and causes the metadata server to be paused. It should not be performed often. The default backup schedule performs a REORG on Monday (WeekDay2="0100R").

<SCHEDULER/>

supported with the REFRESH action, rebuilds or restarts the backup scheduler, depending on the XML subelement that is specified in the <SCHEDULER/> element. The backup scheduler runs continuously from the time the metadata server is started, and buffers the schedule in 48-hour increments. The <SCHEDULER/> XML element restores the scheduler in the event the scheduler is inoperative and backups are not taking place on the specified schedule. You can issue a STATUS method request through PROC METADATA to check the health of the scheduler. For more information, see Use METHOD=STATUS to Get Backup Information. The supported subelements are:

<REBUILD/>

forces the scheduler to rebuild its in-memory linked list of events.

<RESTART/>

causes the current scheduler thread to stop, and then starts a new one.

<SERVER STATE="ADMIN | OFFLINE | READONLY"/>

supported with the PAUSE and RESUME actions, specifies that the action applies to the metadata server. The <SERVER/> XML element has the following uses:

• It is optional for the PAUSE action, and its STATE= parameter is optional. Supported with the PAUSE action, it specifies an access state to apply to the metadata server. With the PAUSE action, if you do not specify the <SERVER STATE="ADMIN | OFFLINE | READONLY"/> XML element, or if you specify <SERVER/> without a STATE= parameter, the default is to pause the metadata server to an offline state, which also sets the repositories to an offline state.
• It is required for the RESUME action without the STATE= parameter when the <FORCE/> option is used.

STATE= has one of the following values:

ADMIN

allows only users with administrative status to read and write metadata on the metadata server.

OFFLINE

disables all Read and Write access to the metadata server.

READONLY

allows Read-Only access for any user.

OUT=SAS-data-set

names the output data set. This argument is used with the STATUS action. Other actions do not create output.