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.
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.
-
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:
-
If you specify REFRESH without
an XML string, or if you specify the <SERVER/> XML element,
the REFRESH action pauses and resumes (in a single step) the metadata
server. Do not specify the STATE= parameter in the <SERVER/>
XML element. The REFRESH action recovers memory on the metadata server,
and reloads authorization inheritance rules.
For more information,
see Submitting ACTION=REFRESH to Pause and Resume the Metadata Server. After the refresh, all repositories return to the same
pause state that they were in before the refresh.
For more information,
see How PAUSE, REFRESH, and RESUME Affect Repositories.
-
-
With the
<OMA ALERTEMAILTEST="text"/> XML element
specified,
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.
-
Note: This option is valid only
when <OMA JOURNALTYPE="SINGLE"/> is specified in the server’s
omaconfig.xml configuration file. Use of the <OMA JOURNALTYPE=”SINGLE”/>
option is discouraged because it disables recovery roll-forward processing.
-
- RESUME
-
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.
- 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=
Copyright © SAS Institute Inc. All rights reserved.