Using the Batch Export Tool

Syntax for the Batch Export Tool

ExportPackage
-host source-host-name
-port source-port-number
-user user-id
-password password
-domain domain-name
<-profile connection-profile-name>
-package package-path-and-filename
-objects source-location-1 source-location-2 source-location-3 ... source-location-n
<-types object-type-1, object-type-2....object-type-n>
<-excludeSubTypes>
<-includeDep>
<-name character-string>
<-nameMatchType CONTAINS | EQUALS | STARTSWITH>
<-includeDesc>
<-keywords keyword>
<-notes character-string>
<-extName extended-attribute-name>
<-extValue extended-attribute-value>
<-respName name-of-responsible-user>
<-respRole OWNER | ADMINISTRATOR>
<-since from-absolute-date | from-relative-date|relative-time-period>
<-before to-absolute-date | to-relative-date>
<-created>
<-modified>
<-includeEmptyFolders>
<-subprop>
<-log log-path | log-path-and-filename | . >
<-noexecute>
<-? | --help>

Syntax Description for the Batch Export Tool

-host source-host-name
specifies the machine name of the metadata server from which the package is being exported.
Requirement Required if –profile is not specified.
-port source-port-number
specifies the port number of the metadata server from which the package is being exported.
Requirement Required if –profile is not specified.
-user user-id
specifies the user ID that is to be used to connect to the source metadata server. Make sure that this user has the appropriate credentials. See Ensure Appropriate User Credentials.
Requirement Required if –profile is not specified, or if the specified connection profile does not contain user credentials.
-password password
specifies the password of the user who is specified in –user.
The password can be encrypted using SAS proprietary 32-bit encryption. To obtain the encrypted password, use PROC PWENCODE. For example, to encrypt the password "mypassword," you would submit this code in the SAS Program Editor:
proc pwencode in="mypassword" method=sas002;
run;
Requirement Required if –profile is not specified, or if the specified connection profile does not contain user credentials.
-domain domain-name
specifies the SAS authentication domain in which the user ID is to be authenticated.
Requirement Not required. You can omit this option if your installation has only one SAS authentication domain. You can also omit this option if you specify –profile and if the specified connection profile contains a domain name.
-profile connection-profile-name
specifies the name of the connection profile that is to be used to connect to the source metadata server. You can specify this option instead of –host, –port, –user, –password, and –domain.
The connection profile must exist on the computer where the export command is executed. You can specify any connection profile that has been created for use with client applications such as SAS Management Console, SAS Data Integration Studio, or SAS OLAP Cube Studio. When you open one of these applications, the available connection profiles are displayed in the drop-down box in the Connect Profile dialog box.
If the connection profile name contains spaces, then use quotation marks. If the connection profile contains a user ID and password, then make sure that the user has the appropriate credentials.
Requirement Not required. You can omit this option if –host and –port are provided.
Interaction If you specify this parameter, then –host, –port, and –domain can be omitted. If the specified connection profile contains a user ID and password, then –user and –password can also be omitted.
-package package-path-and-filename
specifies the path and filename of the package file that you want to create. The objects that you export will be placed in this file.
The filename must have the extension .spk. The path is optional, but if you do specify a path, it must be fully qualified.
If the path or filename includes spaces, then use quotation marks.
CAUTION:
If a file of this name already exists, then it will be overwritten.
If you want to preserve pre-existing packages, then be sure to specify a unique name.
Default If you do not specify a path, then the package is placed in the directory where the command was launched.
Requirement You must specify a filename, but the path is optional.
-objects source-location-1 source-location-2 source-location-3 ... source-location-n
specifies the locations of the objects that are to be exported. You can specify any number of locations. Leave a space between each location. If a location includes spaces, then enclose the location in quotation marks.
Use the following syntax to specify a location:
/folder-1/folder-2/...folder-n/<object-name(object-type)>
The following rules apply to specifying locations:
  • Locations are relative to the SAS Folders node. Therefore, the first folder that you specify in a location must be located directly beneath SAS Folders.
  • If you specify a folder but you do not specify an object name, then all objects and folders beneath that folder are exported.
  • To export objects from your personal folder, you must specify the actual path (/User Folders/user-name/My Folder or /Users/user-name/My Folder) rather than the shortcut (/My Folder). Note that the name of the parent folder for user folders varies depending on the SAS release in which the folders were created.
  • If you specify an object name, then you must also specify the object's type. For a list of object types, see Specifying Object Types. Object types are case-sensitive.
The following are examples of locations:
  • –objects/
    This example exports the entire SAS Folders hierarchy and all of its objects.
  • –objects“/User Folders/sasdemo/My Folder" or –objects"/Users/sasdemo/My Folder"
    This example exports all objects and folders that are in the personal folder of the user named sasdemo.
  • –objects"/Shared Data/Orion Star Data/Customer Orders(InformationMap)".
    This exports the Customer Orders information map, which is located in /Shared Data/Orion Star Data
  • –objects"/Shared Data/Orion Star Data/Customer Orders(InformationMap)" "/Shared Data/Orion Star Data/CUSTOMER_DIM(Table)" "/Shared Data/Orion Star Data/ORDER_FACT(Table)" "/Shared Reports/Orion Star Reports/Sales by Customer Type(Report)"
    This example exports the Customer Orders information map, the CUSTOMER_DIM table, and the ORDER_FACT table, all of which are located in /Shared Data/Orion Star Data; and the Sales by Customer Type report, which is located in /Shared Reports/Orion Star Reports.
Requirement Required
Tips To further limit the objects that are exported, you can use the –types, –name, –since, and –before options.
If you want to automatically export all of the objects on which the exported objects depend (instead of having to explicitly list those objects), specify –includeDep.
-types object-type-1, object-type-2....object-type-n
specifies a comma-separated list of the types of objects that are to be exported. If you specify this option, then the tool exports only objects that are of the specified types; all other objects are ignored.
If the string contains spaces, then use quotation marks.
For a list of object types, see Specifying Object Types. Object types are case-sensitive.
By default, if you specify an object type that has one or more subtypes, then the subtypes are included in the export. For example, if you specify Report, then Report.Component, Report.Image, and Report.StoredProcess are automatically included.
Requirement Not required.
Interaction If you want to exclude subtypes of these object types from the export, then use the –excludeSubTypes option with this option.
Note Folder is not a valid value for the –types option. When an object of the specified type is exported, the folder structure that contains it is also exported.
-excludeSubTypes
specifies that subtypes of the specified object types are to be excluded from the export. In the list of object types, include one or more object types that are specified in the –types option.
For example, suppose you specify the following:
-types Report,Job -excludeSubtypes
Objects with the type Report and Job are included in the export. Objects with the type Job.Cube, Report.Component, Report.Image, and Report.StoredProcess are excluded.
Default If you do not specify –excludeSubTypes with the –types option, then the export automatically includes all subtypes.
Requirement Not required.
-includeDep
specifies that all objects on which the exported objects depend are to be included in the export. If you select this option, the export tool recursively identifies dependencies and includes the identified objects in the export.
For example, if you export an information map, the export tool identifies and exports any libraries, tables, and stored processes that are used by the information map. The process also exports any objects that the identified stored processes depend on.
CAUTION:
If you do not export the objects on which exported objects depend, then the exported objects might not function properly when you import them to the target metadata server.
Requirement Not required
Interaction The identified dependent objects will include all types of objects, regardless of the values that are specified in the –types option.
-name character-string
specifies a character string that must be present in an object's name in order for the object to be exported. Objects whose names contain the specified string are exported, and all other objects are ignored.
This option only identifies objects. It does not apply to folders.
This option is not case sensitive. For example, if you specify –name product, then the tool exports objects with the names Sales by Product and PRODUCT_DIM.
If the string contains spaces, then use quotation marks.
Requirement Not required
Interactions If you specify –includeDesc along with –name, then the object is exported if the text string is present in either the object’s name or its description.
You can use the –nameMatchType option to further define how the –name option is to be applied.
-nameMatchType CONTAINS | EQUALS | STARTSWITH
specifies how the –name option is to be applied. The following values are valid:
CONTAINS specifies that the object’s name must contain the character string that is specified in –name in order for the object to be exported.
EQUALS specifies that object’s name must exactly match the character string that is specified in –name in order for the object to be exported.
STARTSWITH specifies that the object’s name must begin with the character string that is specified in –name in order for the object to be exported.
The matching of character strings is not case sensitive.
Default CONTAINS
Requirement This option is not required.
Interactions This option is ignored if –name is not specified.
This option applies only to the object name. If you specify –includeDesc, this option does not apply to the description.
-includeDesc
specifies that the character string that is specified in –name will be searched for in both the name and the description of each object.
Requirement Not required
Interactions This option is ignored if –name is not specified.
The –nameMatchType option does not apply to the object description. It applies only to the object name.
-keywords keyword
specifies one or more keywords to be used as filtering criteria. If an object has a keyword that exactly matches one or more of the specified keywords, then the object will be included in the export. If a keyword contains spaces, then put it in quotation marks.
-notes character-string
specifies one or more character strings to be used as filtering criteria for public and private Notes. If an object’s public or private Notes field contains one or more of the specified strings, then the object will be included in the export. If a string contains spaces, then use quotation marks.
Only certain types of objects (for example, objects used by SAS Data Integration Studio) support the Notes field.
Requirement Not required
-extName extended-attribute-name
specifies the name of an extended attribute. Objects that have an extended attribute that exactly matches the specified attribute name will be included in the export.
Only certain types of objects (for example, objects used by SAS Data Integration Studio) support extended attributes.
Requirement Not required.
Interaction You can use –extValue to specify a particular value for the attribute.
-extValue extended-attribute-value
specifies a value for the extended attribute that is specified in –extName. Objects that have a value for this attribute that exactly matches the specified value will be included in the export.
Requirement Not required
Interaction This option is ignored if –extName is not specified.
-respName name-of-responsible-user
specifies a user name that must be present in an object’s Responsibilities metadata in order for the object to be exported. The specified name must exactly match the user’s Name field in the metadata.
Requirement Not required.
Interaction You can use –respRole to specify whether the user is to be an owner or an administrator for the object.
-respRole OWNER | ADMINISTRATOR
specifies the role of the user that is specified in –respName. The valid values are OWNER and ADMINISTRATOR. Objects will be exported only if the object’s Responsibilities metadata specifies this role for the user that you specify in –respName.
Requirement Not required
Interaction This option is ignored if –respName is not specified.
-since from-absolute-date | from-relative-date | relative-time-period
specifies that objects are to be exported only if they were created or modified on or after the specified date, or during the specified time period. You can specify one of the following:
from-absolute-date specifies an absolute date.
from-relative-date specifies a date relative to the current date.
relative-time-period specifies a time period relative to the current date.
Requirement Not required
Interaction You can specify either –created or –modified with this option. The default setting is –modified.
See Specifying an Absolute Date (or an Absolute Date and Time), Specifying a Relative Date, and Specifying a Relative Time Period
-before from-absolute-date | from-relative-date
specifies that objects are to be exported only if they were created or modified on or before the specified date. You can specify one of the following:
from-absolute-date specifies an absolute date.
from-relative-date specifies a date relative to the current date.
Requirement No
Interaction You can specify either –created or –modified with this option. The default setting is –modified.
Tip To specify a date range, specify –since along with this option.
See Specifying an Absolute Date (or an Absolute Date and Time) and Specifying a Relative Date
-created
specifies that the –since and –before options are to be based on each object's Created date. If –created is specified, then objects are exported only if the Created date meets the criteria specified in –since and –before.
Default If –since or –before is specified but –created is not specified, then –modified is assumed.
Requirement Not required.
Interaction If you specify both –created and –modified, then –modified takes precedence.
-modified
specifies that the –since and –before options are to be based on each object's Modified date. If –modified is specified, then objects are exported only if the Modified date meets the criteria specified in –since and –before.
Note: If an object has never been modified, then the object's Modified date is equal to its Created date.
Default If –since or –before is specified, and if you specify neither –created nor –modified, then –modified is assumed.
Requirement Not required.
Interaction If you specify both –created and –modified, then –modified takes precedence.
-includeEmptyFolders
specifies that folders are to be exported even if they do not contain any subfolders or objects.
Default If this option is not specified, then empty folders are not exported.
Requirement Not required.
-subprop
specifies that the export tool is to create an external substitution properties file. By default, the export tool always creates a substitution properties file inside of the package file. If you specify this option, then the substitution properties file is created externally.
In this file, you can modify values that are associated with the exported objects so that the objects will function properly in the target system. For example, you can modify server names, source code repository paths, OLAP schema names, and cube names to reflect the names that are used on the target system. You can also use this file to reorganize content by specifying new folder locations for individual objects that you are importing. For detailed instructions, see Using the Substitution Properties File.
Default If you do not specify this option, then an external substitution properties file is not created. The import process will use the source environment's settings for server names, source code repository paths, database schema names, and archive paths and will expect those servers, paths, and schemas to exist in the target environment.
A substitution file is still created inside the package file and can be extracted. See Using the Import SAS Package Wizard to Import a Package That Was Created by the Batch Export Tool.
Requirement Not required.
-log log-path | log-path-and-filename
specifies one of the following:
  • the path (or the path and filename) where the log file is to be written
  • that the log file is to be written to the current directory. To specify this option, use a period, as shown here:
    -log .
The log file contains messages that are generated during the batch tool's execution.
Default If you do not specify this option, then the log is directed to the default log path and filename as described in Viewing the Batch Export or Import Log.
Requirement Not required.
-noexecute
specifies that the package file is not to be created. Instead, a list of all of the objects that are included in the export is displayed, and a log file is created. This option is useful if you want to verify that the command is constructed correctly before you execute it.
Default If you do not specify this option, then the package is exported to the specified package.
Requirement Not required.
[-? | --help]
specifies to display help for the batch export tool.
Requirement Not required.

Special Instructions for z/OS Systems

When entering batch export and import commands on z/OS systems, you might need to precede special characters with a backslash character (\). Characters other than letters (A-Z and a-z), numbers (0-9), underscores (_), hyphens (-), and periods (.) might require a preceding backslash.

About Case Sensitivity

In the batch export and import commands, you must use the correct case for option names (for example, –includeDep and –newOnly) and object types (for example, InformationMap).
All other elements of the commands are case insensitive.

Specifying Object Types

When you use the export batch tool, you might need to specify one or more object types, as follows:
  • in the –objects option, if you specify individual objects. You must specify the object type in parentheses after each object name.
  • in the –types option.
The following table provides a list of object type names that you can use with these options. This list is valid as of the second maintenance release for SAS 9.3.
CAUTION:
Object types are case sensitive. Be sure to enter them exactly as they are shown here.
Note: You might be able to export additional object types, depending on which applications you have installed.
ACT InformationMap PromptGroup
Action InformationMap.OLAP Report
Application InformationMap.Relational Report.Component
ApplicationServer JMSDestination (Java Messaging System message queue) Report.Image
BurstDefinition Job Report.StoredProcess
Channel Job.Cube Role
Condition Library SearchFolder
ConditionActionSet MessageQueue SecuredLibrary
ContentSubscriber MiningResults Server
Cube MQM.JMS (queue manager for Java Messaging Service) Service.SoapGenerated
DataExploration MQM.MSMQ (queue manager for MSMQ) SharedDimension
DeployedFlow MQM.Websphere (queue manager for WebSphere MQ) Spawner.Connect
DeployedJob Note Spawner.IOM (object spawner)
Document OLAPSchema StoredProcess
EventSubscriber Project SubscriberGroup.Content
ExternalFile Project.EG SubscriberGroup.Event
FavoritesFolder Project.AMOExcel Table
Folder Project.AMOPowerPoint User
Folder.SecuredData Project.AMOWord UserGroup
GeneratedTransform Prompt
Note: By default, if you specify an object type that has one or more subtypes, then the subtypes are included in the export. For example, if you specify Report, then Report.Component, Report.Image, and Report.StoredProcess are automatically included.
Note: For server objects, the preceding list does not include all of the various subtypes. If you want to specify a server subtype, you can use SAS Management Console to look up the subtype name. On the Folders tab, navigate to System/Types. On the right pane, right-click an object type and select Properties. The Type Name is displayed on the Advanced tab of the Properties dialog box.

Specifying an Absolute Date (or an Absolute Date and Time)

When you use –since or –before in a batch export command, you can specify an absolute date (or an absolute date and time). Use one of the following formats:
  • ddMMMyyyy
  • ddMMMyyyy:HH:mm:ss
  • ddMMMyy
  • ddMMMyy:HH:mm:ss
  • MM/dd/yyyy
  • MM/dd/yyyy HH:mm:ss
  • yyyyMMdd
  • yyyyMMdd:HH:mm:ss
Note: If you do not specify a time, then the specified date begins at midnight (12:00:00 a.m.) and ends at 11:59:59 p.m.

Specifying a Relative Date

When you use –since or –before in a batch export command, you can specify a date relative to the current date. To specify a relative date, use one of the following values:
Today
is the current date, based on the date and time on the host machine for your client software (for example, SAS Management Console)
Yesterday
is the day just before the current date.
"Current day of last year"
is the same as the current date, except that the year is replaced with the previous year. For example, if the current date is October 12, 2011, then Current day of last year is October 12, 2010. February 29 is replaced with February 28.
"Current day of last month"
is the same as the current date, except that the month is replaced with the previous month. For example, if the current date is October 12, 2011, then "Current day of last month" is September 12, 2011. If the previous month has fewer days, the date is adjusted downward as necessary. For example, if the current date is October 31, 2011, then "Current day of last month" is September 30, 2011.
"Current day of last week"
is seven days previous to the current date. For example, if the current date is October 12, 2011, then Current day of last week is October 5, 2011.
"ndays ago"
is n days previous to the current date. When specifying this option, replace n with an integer.
Note: Dates are assumed to begin at midnight (12:00:00 a.m.) and end at 11:59:59 p.m.

Specifying a Relative Time Period

When you use –since in a batch export command, you can specify a time period that is relative to the current date. To specify a relative time period, specify one of the following values:
"Year to date"
is the period from January 1 of the current year up to and including the current date.
"Month to date"
is the period from the first day of the current month up to and including the current date.
"Week to date"
is the period from the most recent Monday up to and including the current date.
Note: Dates are assumed to begin at midnight (12:00:00 a.m.) and end at 11:59:59 p.m.

Example: Batch Export Command

ExportPackage -profile "My Profile" -package "c:\SAS Promotion Files\Package_1.spk" -objects "/Shared Reports/Orion Star Reports" -includeDep -since "Week to date" -modified -subprop
This command does the following:
  • exports folders, subfolders, and objects from /Shared Reports/Orion Star Reports. Objects are included only if they were created or modified since Monday of the current week.
  • recursively identifies the objects on which the exported objects depend, and exports those objects as well.
  • exports physical content (for example, .SRX files) that is associated with the exported objects.
    Note: When you use the batch tools, the promotion automatically includes all associated content except physical files for tables and external files. (The batch tools do not provide the option of promoting physical files for tables and external files.)
  • creates a package file called Package_1.spk that contains the exported objects and content, and places the file in C:\SAS Promotion Files.
  • creates a substitution properties file called Package_1.subprop, and places the file in C:\SAS Promotion Files.
Copyright © SAS Institute Inc. All rights reserved.