METAOPERATE Procedure

PROC METAOPERATE Statement

Performs administrative tasks associated with the metadata server

Syntax

PROC METAOPERATE <server-connection-arguments>
ACTION = PAUSE | REFRESH | RESUME | DELETE | EMPTY | UNREGISTER
| STATUS | STOP
<NOAUTOPAUSE>
<OPTIONS = "XML–string">
<OUT = SAS-data-set>;

Summary of Optional Arguments

Required Argument

ACTION=
specifies the action that you want to perform.
DELETE
removes the specified repository, and removes the repository's registration from the repository manager. The repository is specified in the REPOSITORY= server connection argument or the METAREPOSITORY= system option. To invoke this action, the user must have access privilege to the repository, the repository must be registered in SAS Management Console as online, and the metadata server cannot be paused offline. The NOAUTOPAUSE argument is required.
EMPTY
removes the metadata records from the specified repository, but does not remove the repository's registration from the repository manager. The repository is specified in the REPOSITORY= server connection argument or the METAREPOSITORY= system option. To invoke this action, the user must have access privilege to the repository, the repository must be registered in SAS Management Console as online, and the metadata server cannot be paused offline. The NOAUTOPAUSE argument is required. For more information, see Submitting ACTION=EMPTY.
PAUSE
in SAS 9.3, PAUSE has the following two uses:
  • Limits the availability of the metadata server by setting the metadata server's state to ADMIN, OFFLINE, or READONLY. The READONLY state is new in SAS 9.3.
    The PAUSE action affects the metadata server, not an individual repository or the repository manager. For more information, see How PAUSE, REFRESH, and RESUME Affect Repositories.
    Issue ACTION=PAUSE and use the OPTIONS= argument to specify a <SERVER STATE="ADMIN"/> or a <SERVER STATE="READONLY”/> XML string. The OPTIONS= argument, the <SERVER/> element, and the STATE= parameter are optional. The default is to pause the metadata server to an offline state, which also sets the repositories in an offline state.
    The <PAUSECOMMENT>text</PAUSECOMMENT>XML element is optional. It enables you to submit free-form text (for example, details about the pause). For more information, see Submitting ACTION=PAUSE with a Pause Comment.
  • When used with the <FORCE/>XML element in the OPTIONS parameter, the PAUSE action regains control of the metadata server during the recovery process in the event that the recovery process stops responding. The server is paused to an offline state unless you specify a different <SERVER STATE=""/> value.
Here are examples of situations that might require you to pause the metadata server to an ADMIN, OFFLINE, or READONLY state:
  • to troubleshoot system errors
  • to install or upgrade software
  • to temporarily make all repositories available for reading only
  • to close repositories and remove the server lock on them to perform a system backup with an external backup tool
  • to terminate a hung recovery process, and move the server into an ADMIN state to perform troubleshooting
REFRESH
affects the metadata server differently depending on the XML string that you specify in the OPTIONS= argument. Here are the choices:
RESUME
restores the paused metadata server to the online state. Beginning in SAS 9.2, the RESUME action affects the metadata server, not an individual repository or the repository manager. For more information, see How PAUSE, REFRESH, and RESUME Affect Repositories and Submitting ACTION=RESUME.
Any text that was specified in the <PAUSECOMMENT>text</PAUSECOMMENT> XML element during the PAUSE action is cleared.
Beginning in SAS 9.3, RESUME supports a <FORCE/> XML element in the OPTIONS="XML-string". argument. <FORCE/> regains control of the metadata server during the recovery process in the event that the recovery process stops responding . The server is returned to an online state. The <SERVER/> XML element is required when <FORCE/> is used.
STATUS
returns the metadata server's SAS version or release number, host operating environment, the user ID that started the metadata server, SAS Metadata Model version number, and whether the metadata server is paused or running. For more information, see Submitting ACTION=STATUS.
STOP
stops all client activity, and terminates the metadata server. In complex environments, the metadata server shutdown can take a few minutes. Therefore, PROC METAOPERATE might finish executing before the metadata server finishes its shutdown. Metadata in repositories is unavailable until the metadata server is restarted. You cannot restart the metadata server with PROC METAOPERATE.
UNREGISTER
removes the repository's registration from the repository manager, but does not remove the metadata records from the repository, and does not remove the repository from disk. The repository is specified in the REPOSITORY= server connection argument or the METAREPOSITORY= system option. To invoke this action, the user must have access privilege to the repository, the repository must be registered in SAS Management Console as online, and the metadata server cannot be paused offline. The NOAUTOPAUSE argument is required.
Requirement:You must have the appropriate SAS Administrator role on the metadata server to execute all actions except STATUS.
Tips:Specifying more than one XML element in a PROC METAOPERATE statement might cause unwanted results. Use more than one XML element only when specified in the documentation.

If you use PROC METAOPERATE to delete, empty, or unregister a project repository, you must first make sure that no metadata is checked out to that project repository. See SAS Data Integration Studio documentation for information about unlocking any checked out objects. Or, you can use SAS Management Console to delete, empty, or unregister a project repository. SAS Management Console unlocks any checked-out objects before it performs the action.

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.
<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.

Server Connection Arguments

The server connection arguments establish communication with the metadata server. If you omit these arguments, then the values of the system options are used, or the values can be obtained interactively. For more information, see Connection Options .

PASSWORD="password"
is the password for the authenticated user ID on the metadata server. If you do not specify PASSWORD=, the value of the METAPASS= system option is used. For more information, see METAPASS= System Option. The maximum length is 512 characters.
Alias:METAPASS= or PW=
PORT=number
is the TCP port that the metadata server listens to for connections. This port number started the metadata server. If you do not specify PORT=, the value of the METAPORT= system option is used. For more information, see METAPORT= System Option. The range of allowed port numbers is 1 to 65535. The metadata server is configured with a default port number of 8561.
Alias:METAPORT=
Requirement:Do not enclose the value in quotation marks.
PROTOCOL=BRIDGE
is the network protocol for connecting to the metadata server. If you do not specify PROTOCOL=, the value of the METAPROTOCOL= system option is used. For more information, see METAPROTOCOL= System Option. In this release, the only supported value is BRIDGE, which specifies the SAS Bridge protocol. This is the server default, so there is no need to specify this argument.
Alias:METAPROTOCOL=
Requirement:Do not enclose the value in quotation marks.
REPOSITORY="name"
is the name of an existing repository. This value is the repository's Name= parameter. The REPOSITORY= argument is required when the action is UNREGISTER, DELETE, or EMPTY. For other actions, if you do not specify REPOSITORY=, the value of the METAREPOSITORY= system option is used. For more information, see METAREPOSITORY= System Option. The default for the METAREPOSITORY= system option is FOUNDATION. The maximum length is 32,000 characters.
Alias:METAREPOSITORY= or REPOS=
SERVER="host-name"
is the host name or network IP address of the computer that hosts the metadata server. The value LOCALHOST can be used if the SAS session is connecting to the metadata server on the same computer. If you do not specify SERVER=, the value of the METASERVER= system option is used. For more information, see METASERVER= System Option. The maximum length is 256 characters.
Alias:HOST= or IPADDR= or METASERVER=
USER="authenticated-user-ID"
is an authenticated user ID on the metadata server. The metadata server supports several authentication providers. For more information about controlling user access to the metadata server, see the SAS Intelligence Platform: Security Administration Guide. If you do not specify USER=, the value of the METAUSER= system option is used. For more information, see METAUSER= System Option. The maximum length is 256 characters.
Alias:ID= or METAUSER= or USERID=