sas studio 3...repository within sas studio. to change a global repository, an administrator or...

SAS® Studio 3.5Developer’s Guide to Repositories

SAS® Documentation

The correct bibliographic citation for this manual is as follows: SAS Institute Inc. 2016. SAS® Studio 3.5: Developer's Guide to Repositories. Cary, NC: SAS Institute Inc.

SAS® Studio 3.5: Developer's Guide to Repositories

Copyright © 2016, SAS Institute Inc., Cary, NC, USA

All rights reserved. Produced in the United States of America.

For a hard-copy book: No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, or otherwise, without the prior written permission of the publisher, SAS Institute Inc.

For a web download or e-book: Your use of this publication shall be governed by the terms established by the vendor at the time you acquire this publication.

The scanning, uploading, and distribution of this book via the Internet or any other means without the permission of the publisher is illegal and punishable by law. Please purchase only authorized electronic editions and do not participate in or encourage electronic piracy of copyrighted materials. Your support of others' rights is appreciated.

U.S. Government License Rights; Restricted Rights: The Software and its documentation is commercial computer software developed at private expense and is provided with RESTRICTED RIGHTS to the United States Government. Use, duplication or disclosure of the Software by the United States Government is subject to the license terms of this Agreement pursuant to, as applicable, FAR 12.212, DFAR 227.7202-1(a), DFAR 227.7202-3(a) and DFAR 227.7202-4 and, to the extent required under U.S. federal law, the minimum restricted rights as set out in FAR 52.227-19 (DEC 2007). If FAR 52.227-19 is applicable, this provision serves as notice under clause (c) thereof and no other notice is required to be affixed to the Software or documentation. The Government's rights in Software and documentation shall be only those set forth in this Agreement.

SAS Institute Inc., SAS Campus Drive, Cary, North Carolina 27513-2414.

May 2016

SAS® and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. ® indicates USA registration.

Other brand and product names are trademarks of their respective companies.

Contents

Using This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

PART 1 Working with Repositories 1

Chapter 1 / Accessing Existing Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3What Is a Repository? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3How to Access Repositories in SAS Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Creating Global Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

PART 2 Developing New Repositories 7

Chapter 2 / Installing and Configuring the Repository Toolkit Appliance . . . . . . . . . . . . . . . . . . . . . . . 9About the Repository Toolkit Appliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Download and Import the Repository Toolkit Appliance . . . . . . . . . . . . . . . . . . . . . 9Configure the Repository ToolKit Appliance in VirtualBox . . . . . . . . . . . . . . . . . . 11Create an FTP Shortcut to Access Repository Files in SAS Studio . . . . . . . . . . 13

Chapter 3 / Understanding the Files in a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Overview of the Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17About the repository.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17About the tasks.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18About the snippets.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19About the repository.html File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

PART 3 Learning by Example 23

Chapter 4 / Snippets Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25About the Snippets Repository Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Access the Snippets Repository in SAS Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Organizing Snippets into Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Specifying an Icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Linking to Documentation for a Repository or a Snippet Category . . . . . . . . . . . 30Referencing Data Files in the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 5 / Macros Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35About the Macro Repository Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Access the Macro Repository in SAS Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Referencing a Macro from a Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Referencing a Macro from a Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 6 / Saved Task Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41About the Saved Task Repository Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Access the Saved Task Repository in SAS Studio . . . . . . . . . . . . . . . . . . . . . . . . 42Referencing CTM and CTK Task Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Recommended Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

iv Contents

Using This Book

Audience

This documentation is for users who need to develop a SAS Studio repository.

The specifics of how you deploy a repository are not covered in this documentation. You can deploy repositories using web-hosting services, source management services such as GitHub, or your own web content system. The process for deploying repositories depends on the setup at your site.

Requirements

Prerequisites

To access repositories in SAS Studio, your SAS Studio administrator must set the webdms.allowRepositories and webdms.globalSettings configuration properties. For more information about these configuration properties, see SAS Studio: Administrator's Guide.

To develop your repository, you can use a variety of tools. If you are already familiar with web hosting, you can use the tool that you are already familiar with. If you are not familiar with developing repositories, SAS Studio provides a Repository Toolkit Appliance that you can use for development. To run this toolkit, you must install Oracle VirtualBox. For more information, see Chapter 2, “Installing and Configuring the Repository Toolkit Appliance,” on page 9.

Using a Web-Hosting Service

SAS Studio repositories contain multiple file types. Because of the same-origin policy, you must use a web-hosting service such as GitHub and the Repository Toolkit Appliance. You cannot use a site that cannot host HTML web content with embedded Javascript. For example, Google Drive, Drop Box, and Microsoft SharePoint are file-hosting mechanisms that cannot host true web content.

Security Considerations

The security for the SAS Studio repositories depends on these security models:

n The best security is where the repository is deployed. For example, the repository can be deployed inside a firewall for maximum security or outside a firewall for lower security.

n Basic web authentication is supported.

v

n When possible, SAS Studio uses the existing security from external sources.

Because of security concerns, you might want to prevent users from adding any user-defined repositories to their SAS Studio sessions. When the webdms.allowRepositories property is set to false, the Repositories section is not available in the Preferences window in SAS Studio. To allow users to add user-defined repositories, set the webdms.allowRepositories property true.

Note: If defined, global repositories are always available to the SAS Studio user from the Tasks and Utilities and Snippets sections in the navigation pane. Global repositories are not listed in the Repositories section of the Preferences window. The location of the global repository is defined by the webdms.globalSettings configuration property.

vi Using This Book

Part 1

Working with Repositories

Chapter 1Accessing Existing Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1

1Accessing Existing Repositories

What Is a Repository? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

How to Access Repositories in SAS Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Creating Global Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

What Is a Repository?

SAS Studio repositories are an easy way for you to share tasks and snippets with other users at your site. Currently, you might be sharing tasks by sending the CTM files through email. This method quickly results in out-of-date content. You might also be sharing tasks and snippets by using a network location. However, a SAS Studio user has to upload these files into their SAS Studio session before they can access these tasks or snippets.

Repositories provide a solution to both issues. Maintenance is easier because all the source files are in one place. To view the contents of a repository, the SAS Studio user simply sets a preference in their SAS Studio session. After this preference is set, any tasks and snippets in the repository are visible from the Task and Utilities and Snippets sections in the SAS Studio navigation pane. If you (the developer of the repository) add content to the repository, the SAS Studio user simply needs to refresh the content of the Task and Utilities and Snippets sections to view your changes.

How to Access Repositories in SAS Studio

1 Click and select Preferences. The Preferences window appears.

2 From the navigation pane, select Repositories.

3 In the Repositories pane, click .

4 In the Add Repository window, complete these steps:

a Specify the name of the repository (as you want the name to appear in SAS Studio).

3

b Specify the URL for the repository.

c Click Add.

The repository that you added is now listed in the Preferences window.

5 Click Save to close the Preferences window.

After a repository is specified in your preferences, you can access any tasks or snippets in that repository from the Tasks and Utilities section or the Snippets section in the navigation pane.

4 Chapter 1 / Accessing Existing Repositories

In this example, the Simple Repository contains one task and one snippet. To view the task, open the Tasks and Utilities section in the navigation pane.

To view the snippet, open the Snippets section in the navigation pane.

Creating Global Repositories

You might have a repository (or multiple repositories) that you want to make available to everyone at your site. Instead of requiring each SAS Studio user to add these repositories through the Preferences window, you can create global repositories. Global repositories are automatically available from the Tasks and Utilities and Snippets sections when you first open SAS Studio.

To create a global repository:

1 Create a repositories.xml file that lists all the repositories you want to include.

The following repositories.xml file combines the Simple Repository, Snippet Repository, Macro Repository, and Saved Task Repository.

<?xml version="1.0" encoding="UTF-8"?>

Creating Global Repositories 5

<Repositories><Repository uri="http://my-repository/Repository/simple" name="Simple Repository" /><Repository uri="http://my-repository/Repository/snippets" name="Snippet Repository" /><Repository uri="http://my-repository/Repository/macros" name="Macro Repository" /><Repository uri="http://my-repository/Repository/tasks" name="Saved Task Repository" /></Repositories>

2 Save the repositories.xml file to your global preferences directory. (You specified this directory by using the webdms.globalSettings property in the config.properties file.)

Now, global repositories are available to the SAS Studio users at your site.

Note: Global repositories are not listed in the Repositories section of the Preferences window. SAS Studio users cannot change the contents of a global repository within SAS Studio. To change a global repository, an administrator or developer with Write permission must edit the repositories.xml file in the global preferences directory.

To allow SAS Studio users to add to their own repositories, set the webdms.allowRepositories property to true in the config.properties file. Now, users can add user-defined repositories to their SAS Studio session by using the Preferences window.

For more information about these configuration properties, see SAS Studio: Administrator's Guide.

6 Chapter 1 / Accessing Existing Repositories

Part 2

Developing New Repositories

Chapter 2Installing and Configuring the Repository Toolkit Appliance . . . . . . . . . . . . 9

Chapter 3Understanding the Files in a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

7

2Installing and Configuring the Repository Toolkit Appliance

About the Repository Toolkit Appliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Download and Import the Repository Toolkit Appliance . . . . . . . . . . . . . . . . . . . . . . 9

Configure the Repository ToolKit Appliance in VirtualBox . . . . . . . . . . . . . . . . . . . 11

Create an FTP Shortcut to Access Repository Files in SAS Studio . . . . . . . . . . 13

About the Repository Toolkit Appliance

If you are not familiar with creating and hosting web content, SAS provides a Repository Toolkit Appliance that you can use to develop a repository without having to understand all the details of web hosting, FTP, or publishing the repository. After you create and test your repository files, you need to give these files to your web services group for publishing.

The appliance contains these items:

n an Apache Web Service with sample repositories.

n an FTP server, so you can edit the repositories in SAS Studio.

Note: If you are familiar with creating and hosting web content, you can use whatever tool you prefer for creating repositories. For more information, see Chapter 3, “Understanding the Files in a Repository,” on page 17.

Download and Import the Repository Toolkit Appliance

1 Download the Repository Toolkit Appliance from the SAS Studio section of the Downloads and Hot Fixes page on support.sas.com.

2 Open the RepositoryAppliance.ova file in Oracle VirtualBox. The Import Virtual Appliance dialog box appears.

9

http://support.sas.com/downloads/index.htm

3 Click Import.

The SAS Studio Repository ToolKit is now available.

10 Chapter 2 / Installing and Configuring the Repository Toolkit Appliance

Configure the Repository ToolKit Appliance in VirtualBox

1 To start the appliance in VirtualBox, select SAS Studio Repository Toolkit and click Start. After verifying network connectivity, the SAS Studio Repository Toolkit [Running] - Oracle VM VirtualBox window appears.

Configure the Repository ToolKit Appliance in VirtualBox 11

The default host name is repository-sdk. You should change this name for your environment.

2 To change the default host name, press CTRL+C.

3 At the command prompt, enter sudo sethost appliance-name. For this example, the appliance name is my-repository. Press Enter.

4 When prompted for a password, enter Power2no! and press Enter.

5 When prompted to reboot the virtual machine, press Enter.

After the virtual machine reboots, the SAS Studio Repository Toolkit [Running] - Oracle VM VirtualBox opens again, but this time, you should see the name of your repository.


In this example, the name specified for the appliance was my-repository.

Note: When you change the appliance name, the links to the documentation and examples at http://repository-sdk are no longer valid. Use the URLs (such as http://my-repository.na.sas.com) that appear in the new console window to access the repository documentation and examples.

Create an FTP Shortcut to Access Repository Files in SAS Studio

If you are using the Repository Toolkit Appliance, you want to create an FTP folder shortcut to your repository so that you can edit the repository’s XML files directly in SAS Studio.

This example creates a shortcut called My Sample Repository. This shortcut points to the files that you downloaded as part of the Repository Toolkit Appliance.

1 In the navigation pane, click Server Files and Folders. Click and select Folder Shortcut. The New Folder Shortcut window appears.

2 Specify a name for the shortcut, such as My Sample Repository.

3 From the Folder type drop-down list, select FTP Folder.

4 Enter the host name that appears on the SAS Studio Repository Toolkit Configuration screen. In this example, the host name is my-repository.

Create an FTP Shortcut to Access Repository Files in SAS Studio 13

5 Enter the studio as the user ID and Power2no! as the password.

6 In the Directory box, enter ~/Repository.

7 Click Test to verify that your information is correct.

8 Click Save.

My Sample Repository now appears in your list of folder shortcuts. If you expand this folder, you see that it contains several directories.

n The macros folder contains the files for the Macro Repository. For more information, see Chapter 5, “Macros Repository,” on page 35.

n The simple folder contains the files for the Simple Repository. For more information, see Chapter 3, “Understanding the Files in a Repository,” on page 17.

n The snippets folder contains the files for the Snippets Repository. For more information, see Chapter 4, “Snippets Repository,” on page 25.


n The tasks folder contains the files in the Saved Tasks Repository. For more information, see Chapter 6, “Saved Task Repository,” on page 41.

Create an FTP Shortcut to Access Repository Files in SAS Studio 15

3Understanding the Files in a Repository

Overview of the Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

About the repository.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

About the tasks.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

About the snippets.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

About the repository.html File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Overview of the Components

Whether you deploy a repository internally or use a web-hosting service, the structure and contents of the repository are the same. A repository can contain multiple file types, such as graphics, data files, and PDF files. However, all repositories must contain these XML files:

n the repository.xml file, which contains the repository definition.

n a tasks.xml or a snippets.xml file. You must have at least one of these files in your repository, but you could have both. You also could have multiple tasks.xml and snippets.xml files. These files create the task definitions and the snippet definitions for the categories that you defined in the repository.xml file.

n the repository.html file. You use this file to access the repository outside of SAS Studio. Open this HTML file in a web browser to validate and test your repository.

Note: To comply with the same-origin policy, all files must be saved in the same domain. You cannot have resources in multiple domains. For example, you cannot create a repository where some of the XML files are in a network directory and some of the files are in Github.

About the repository.xml File

The repository.xml file defines the repository. You can edit this file using an external application, such as NotePad, or by using SAS Studio.

17

Note: In the repository.xml file, any special characters that are part of a name must be represented by an escape character. If any of the names in the XML file contain a special character, the XML parser fails. For example, if you use the ampersand sign (&), the XML parser fails. Instead, you need to use &.

In the My Sample Repository, open simple/repository.xml in the SAS Studio workspace. This is the repository.xml file for the Simple Repository. You should see this code:


1 <Repository label="Example SAS Studio Repository" version="1.0">

2 <Tasks> <Category label="Example Tasks"> <Location uri="./data/tasks.xml" /> </Category> </Tasks>

3 <Snippets> <Category label="Example Snippets"> <Location uri="./sgplot/snippets.xml" /> </Category> </Snippets>

</Repository>

1 The repository.xml file starts with the Repository element, which contains the label and version attributes. These attributes are required.

2 Use the Tasks element to group categories of tasks. You must have at least one category. The category appears under the name of the repository in the Tasks and Utilities section of the navigation pane. Specify the name of the category by using the label parameter.

Each Category element must contain a Location element. You specify the location of the tasks.xml file (which defines the tasks in that category) using the uri parameter. This path can be relative or absolute.

3 Use the Snippets element to group categories of snippets. You must have at least one category. The category appears under the name of the repository in the Snippets section of the navigation pane. Specify the name of the category by using the label parameter.

Each Category element must contain one Location element. You specify the location of the snippets.xml file (which defines the tasks in that category) using the uri parameter. This path can be relative or absolute.

About the tasks.xml File

The tasks.xml file lists the tasks in a category. You need a tasks.xml file for every task category that you create.

18 Chapter 3 / Understanding the Files in a Repository

Because the simple repository contains only one category, all the task-related files are stored in the data directory.

Double-click the tasks.xml file to open it in the workspace. You should see this code:

<?xml version="1.0" encoding="UTF-8"?>1 <Tasks>

2 <Task> <Name label="List Data"/> <Template uri="./ListData.ctm"/> </Task>

</Tasks>

1 Use the Tasks element to group all tasks into a single category. This element must contain one or more Task elements.

2 Use the Task element to define each task in the category. Both the Name and Template elements are required. The Name element specifies the name of the task by using the required label attribute. The Template element specifies the location of the CTM or CTK file by using the required uri attribute. The location of the CTM or CTK file can be relative or absolute.

In the simple repository, the ListData.ctm file is saved with the tasks.xml file in the data directory.

About the snippets.xml File

The snippets.xml file lists the snippets in a single category. You need a snippets.xml file for every snippet category that you create.

About the snippets.xml File 19

Because the Simple Repository contains only one category, all the snippet-related files are stored in the sgplot directory.

Double-click the snippets.xml file to open it in the workspace. You should see this code in the workspace:

<?xml version="1.0" encoding="UTF-8"?>1 <Snippets>

2 <Snippet> <Name label="Needle Plot"/> <Template uri="./needle.sas"/> </Snippet>

</Snippets>

1 Use the Snippets element to group all snippets into a single category. This element must contain one or more Snippet elements.

2 Use the Snippet element to define each snippet in the category. Both the Name and Template elements are required. The Name element specifies the name of the snippet using the required label attribute. The Template element specifies the location of the SAS file using the required uri attribute. The location of the SAS file can be relative or absolute.

In the simple repository, the needle.sas file is saved with the snippets.xml file in the sgplot directory.


About the repository.html File

The repository.html file enables you to test and validate that everything is working correctly. Any warnings or errors generated when trying to load the repository appear on the repository.html page.

Here is the repository.html file for the Simple Repository.

To create the repository.html file for your repository, copy the repository.html file that is shipped with the Repository Toolkit Appliance and save it to the directory that contains your repository files. You do not need to create a new repository.html file.

About the repository.html File 21

Part 3

Learning by Example

Chapter 4Snippets Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 5Macros Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 6Saved Task Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

23

4Snippets Repository

About the Snippets Repository Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Access the Snippets Repository in SAS Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Organizing Snippets into Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Specifying an Icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Linking to Documentation for a Repository or a Snippet Category . . . . . . . . . . . 30

Referencing Data Files in the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

About the Snippets Repository Example

This repository has several snippet categories defined with SAS code taken from the SAS Knowledge Base and Reference on http://support.sas.com. If you need to provide SAS samples or fragments of SAS code to others in your organization, this repository is a good place to start.

This example demonstrates the following functionality:

n defining multiple snippets and snippet categories

n specifying an icon for a repository and for an individual snippet

n referring to documentation that is saved with the repository and documentation that is external to the repository

n referencing data files in the repository

Access the Snippets Repository in SAS Studio




25


a For the name of the repository, enter Snippets Repository.

b For the URL for the repository, enter http://my-repository/Repository/snippets/repository.html.

c Click Add.

The repository that you selected is now listed in the Preferences window.

In the navigation pane, click Snippets to view the contents of this repository. (You might need to refresh the contents of this section to view the new repository.)

Organizing Snippets into Categories

In the Server Files and Folders section of the navigation pane, double-click the snippets/repository.xml file. You can see that this repository contains three categories of snippets: SGPlot Samples, Import Snippets, and DBMS Snippets.


<Repository label="Example SAS Studio Repository" version="1.0">

<Icon uri="http://icons.iconarchive.com/icons/3xhumed/cryonic-folder/ 128/Folder-Blank-sample-icon.png"/> <Documentation uri="./sample.pdf" label="Embedded Repository Documentation (via PDF)"/> <Documentation uri="http://support.sas.com/documentation/cdl/en/ proc/67916/HTML/default/viewer.htm#

26 Chapter 4 / Snippets Repository

p19bcwkxesgd19n1ciwhc8l95s6s.htm" label="Procedures Guide"/>

<Snippets>

<Category label="SGPlot Samples"> <Documentation uri="http://support.sas.com/documentation/cdl/en/ grstatproc/67909/HTML/default/viewer.htm# p073bl97jzadkmn15lhq58yiy2uh.htm" label="SAS(R) 9.4 ODS Graphics: Procedures Guide, Fifth Edition"/> <Documentation uri="http://support.sas.com/documentation/cdl/en/ proc/67916/HTML/default/viewer.htm# p19bcwkxesgd19n1ciwhc8l95s6s.htm" label="Procedures Guide"/> <Location uri="./sgplot/snippets.xml"/> </Category>

<Category label="Import Snippets"> <Documentation uri="https://support.sas.com/documentation/cdl/en/ proc/67916/HTML/default/viewer.htm# n18jyszn33umngn14czw2qfw7thc.htm" label="PROC IMPORT Statement"/> <Location uri="./import/snippets.xml"/> </Category>

<Category label="DBMS Snippets"> <Documentation uri="https://support.sas.com/documentation/cdl/en/ acreldb/68028/HTML/default/viewer.htm#titlepage.htm" label="SAS/ACCESS® 9.4 for Relational Databases"/> <Location uri="./access/snippets.xml"/> </Category>

</Snippets>

</Repository>

These categories are organized into separate directories to keep your files organized and easy to manage.

n The access directory contains the files for the DBMS Snippets category.

n The import directory contains the files for the Import Snippets category.

n The sgplot directory contains the files for the SGPlot Samples category.

Organizing Snippets into Categories 27

Specifying an Icon

In SAS Studio, icons are used to help quickly identify a task, snippet, or repository. You can specify custom icons to identify each task, snippet, and repository.

Here is an example of the Icon element in the repository.xml file for the Snippets Repository.


<Repository label="Example SAS Studio Repositories"> <Icon class="" uri="./repository.png"/>

...</Repository>

In the Icon element, the path to the icon can be absolute or relative. In this example, the repository.png file is saved in the same directory as the repository.xml file, so the path is relative. When you view the repository in SAS Studio, you see the repository.png icon next to Snippets Repository in the Snippets sections of the navigation pane.


You can also use the Icon element in the tasks.xml and snippets.xml files to specify icons for individual tasks and snippets. For example, here is part the snippets.xml file for the DBMS Snippets category. The highlighted code shows the Icon element for the Assign Oracle Library snippet.

<Snippets> <Snippet> <Name label="Assign Oracle Library"/> <Documentation uri="https://support.sas.com/documentation/cdl/en/ acreldb/68028/HTML/default/viewer.htm# p1ujrhdoe1p743n12awcf7mwyg81.htm" label="SAS/ACCESS Interface to Oracle"/> <Template uri="./oracle.sas"/> <Icon uri="http://rocketdock.com/images/screenshots/oracle.png"/> </Snippet>…<Snippets>

In this case, the icon is available from an external site, so when SAS Studio loads the repository, it pulls the image from this external site. As a result, the icon from the external site appears next to Assign Oracle Library.

Specifying an Icon 29

Linking to Documentation for a Repository or a Snippet Category

To help your users understand the contents of the repository and to provide instructions on how to use the repository, you might want to provide custom documentation or link to external documentation (such as SAS documentation on support.sas.com). You can provide documentation for a repository, task, or snippet by using the Documentation element.

Here is an example of Documentation elements in the repository.xml file for the Snippets Repository.


<Repository label=”Example SAS Studio Repository” version=”1.0”>

<Icon url=”http://icons.iconarchive.com/icons/3xhumed/cryonic folder/128/Folder-Blank-sample-icon.png"/> 1 <Documentation uri="./sample.pdf" label="Embedded Repository Documentation (via PDF)"/> 2 <Documentation uri="http://support.sas.com/documentation/cdl/ en/proc/67916/HTML/default/viewer.htm#p19bcwkxesgd19n1ciwhc8l95s6s.htm" label="Procedures Guide"/>

…

</Repository>


1 The first Documentation element uses a relative path because the sample.pdf file is saved with the other files in the repository.

2 The second Documentation element uses an absolute path because it is referring to SAS Procedures Guide, which is available at http://support.sas.com/documentation/cdl/en/proc/68954/HTML/default/viewer.htm#p19bcwkxesgd19n1ciwhc8l95s6s.htm.

To view these links in SAS Studio, select the name of the repository (in this example, Snippets Repository) in the Snippets section of the navigation pane.

Then click .

The documentation links are available from the Properties window.

When you click Embedded Repository Documentation (via PDF), the PDF version of the documentation opens from this URL: http://my-repository/Repository/snippets/sample.pdf.

When you click Procedures Guide, a new tab opens in your web browser and shows the HTML version of the SAS Procedures Guide at support.sas.com.

You can also use the Documentation element to add documentation to individual snippets .Here is an example of a Documentation element in the access/snippets.xml file:

<Snippet> <Name label="Assign Oracle Library"/> <Documentation uri="https://support.sas.com/documentation/cdl/en/acreldb/ 68028/HTML/default/viewer.htm#p1ujrhdoe1p743n12awcf7mwyg81.htm" label="SAS/ACCESS Interface to Oracle"/> <Template uri="./oracle.sas"/> <Icon uri="http://rocketdock.com/images/screenshots/oracle.png"/></Snippet>

To view this documentation, select the Assign Oracle Library snippet in the

Snippets section of the navigation pane. Click .

Linking to Documentation for a Repository or a Snippet Category 31

In the Properties window, you see the link to the SAS/ACCESS Interface to Oracle documentation.

Referencing Data Files in the Repository

You can also include data files (such as XLS, TXT, and CSV) in a repository. In the Snippets Repository, the import folder contains three data files: auto.xls, delimiter.txt, and sample.csv.


Here is the content of the import_xls.sas file:

filename url url "{baseURL}/auto.xls";filename xls temp;

data _null_; infile url recfm=f lrecl=1; file xls recfm=f lrecl=1; input x $char1.; put x $char1.; run;

proc import out = WORK.auto1 datafile=xls dbms=xls replace; sheet="auto1"; getnames=yes;run;

proc print;run;

This code assumes that the SAS server can access URLs where the repository resides by leveraging the power of the FILENAME Statement, URL Access Method. The SAS code is saved in the same location as the external file. You can reference this data from your SAS code by using {baseURL}, which resolves the repository URL when accessed.

For more information about the FILENAME statement, URL Access Method, see SAS Statements: Reference.

Referencing Data Files in the Repository 33

5Macros Repository

About the Macro Repository Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Access the Macro Repository in SAS Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Referencing a Macro from a Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Referencing a Macro from a Snippet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

About the Macro Repository Example

This repository includes a task and a snippet that use SAS macros. The macros are saved in the qr_macros.sas file. The FILENAME statement in the task (the qr_code.ctm file) and the snippet (the qr.sas file) use the URL Access Method to %INCLUDE the repository macros.

35

Access the Macro Repository in SAS Studio





a For the name of the repository, enter Macro Repository.

b For the URL of the repository, enter http://my-repository/Repository/macros/repository.html.

c Click Save.


Referencing a Macro from a Task

The Macro Repository contains only one task. To view the Generate QR code task, open the Tasks and Utilities section in the navigation pane.

Because this repository contains only one task, the code in the tasks.xml file is pretty simple.

<?xml version="1.0" encoding="UTF-8"?><Tasks>

36 Chapter 5 / Macros Repository

<Task> <Name label="Generate QR Code"/> <Template uri="./qr_code.ctm"/> <Icon uri="https://cdn2.iconfinder.com/data/icons/ windows-8-metro-style/512/qr_code.png"/> </Task></Tasks>

The Template element refers to the CTM file that contains the XML code, Apache Velocity code, and SAS code needed to run the task. (For more information about how to write a SAS Studio task, see SAS Studio: Developer's Guide to Writing Custom Tasks.) Because this CTM file is saved in the repository, the Template element uses a relative path.

Here is the code in the qr_code.ctm file:

<?xml version="1.0" encoding="UTF-8"?><Task schemaVersion="4.0" runNLS="never"> <Registration> <Name>Generate a QR Code</Name> <Description>Generate a QR Code</Description> <GUID>*</GUID> <Procedures>HTTP</Procedures> <Version>3.5</Version> <Links> <Link href="http://support.sas.com/kb/45/594.html">Generating a QR Code using PROC HTTP</Link> </Links> </Registration> <Metadata> <DataSources> </DataSources>

<Options> <Option name="OPTIONSTAB" inputType="string">OPTIONS</Option> <Option name="textEXAMPLE" defaultValue="My QR Code" inputType="inputtext" indent="1" required="true" promptMessage="Text for your QR Code" missingMessage="Missing text.">Input text:</Option> </Options> </Metadata> <UI> <Container option="OPTIONSTAB"> <OptionItem option="textEXAMPLE"/> </Container> </UI> <CodeTemplate> <![CDATA[filename url url "{baseURL}/qr_macros.sas";%include url;

Referencing a Macro from a Task 37

filename code temp;data _null_; file code; put "$textEXAMPLE"; output;run;

%generate_qr_code(code,_dataout);

%let _DATAOUT_MIME_TYPE=image/png;%let _DATAOUT_NAME=qrcode.png;

]]> </CodeTemplate></Task>

In the CTM file, the Registration, Metadata, and UI elements define the user interface for the task.

When you run the Generate QR Code task in SAS Studio, you see this user interface:

The content of the CodeTemplate element generates the SAS code that is needed to run the task. The FILENAME statement uses the URL Access Method to point to the qr_macros.sas file, which contains the macro code.

Here is the code for the qr_macro.sas file:

/* Have whatever text you want in the first fileref, and reference a PNG file in the second fileref. Use this macro to produce a QR image of the text. You can have up to 4K of text in the input file. For example: filename mypgm 'mypgm.sas'; filename myqr 'qr.png'; %to_qr ( mypgm , myqr ); */

%macro generate_qr_code(in,out);

/*this data step generates a string of attributes required by the web service.*/data; infile &in recfm=f lrecl=4096 length=l; length url_encoded $8192; keep url_encoded; input @1 all $varying4096. l; url_encoded = 'chs=500x500&cht=qr&chl=' || urlencode(strip(all)) || '&chld=l'; call symputx('qrtextl',length(url_encoded)); output; stop;


run;

filename qrtext temp recfm=f lrecl=&qrtextl;

/* This data step writes to a text file the input that PROC HTTPwill use to call the web service. */data _null_; set; file qrtext; put url_encoded; run;

proc delete; run;

/*call the web service*/proc http in=qrtext out=&out method='post' url='https://chart.googleapis.com/chart?' ct='application/x-www-form-urlencoded'; run;filename qrtext clear;%mend;

Referencing a Macro from a Snippet

The Macro Repository contains only one snippet. To view the Generate QR Code snippet, open the Snippets section in the navigation pane.

Because this repository contains only one snippet, the code in the snippets.xml is pretty simple.

<?xml version="1.0" encoding="UTF-8"?><Snippets> <Snippet> <Name label="Generate QR Code"/> <Documentation uri="http://support.sas.com/kb/45/594.html" label="Generating a QR Code using PROC HTTP"/> <Template uri="./qr.sas"/> <Icon uri="https://cdn2.iconfinder.com/data/icons/

Referencing a Macro from a Snippet 39

windows-8-metro-style/512/qr_code.png"/> </Snippet> </Snippets>

As shown by the reference in the Template element, the snippet is created using code in the qr.sas file (which is saved in the repository).

Here is the content of the qr.sas file:

filename url url "{baseURL}/qr_macros.sas";%include url;

filename code temp;data _null_; file code; put "proc print data=sashelp.fish;run;"; output;run;

%generate_qr_code(code,_dataout);

%let _DATAOUT_MIME_TYPE=image/png;%let _DATAOUT_NAME=qrcode.png;

In qr.sas, the FILENAME statement uses the URL Access Method to point to the qr_macros.sas file, which contains the macro code. When you run the snippet, {baseURL} resolves to the repository URL.


6Saved Task Repository

About the Saved Task Repository Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Access the Saved Task Repository in SAS Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Referencing CTM and CTK Task Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

About the Saved Task Repository Example

This repository includes only tasks. SAS Studio has two types of task files.

n A CTM file is the XML and Apache Velocity code that is used to create the user interface and generate the SAS code for the task.

n A CTK file is a task that is saved with one or more options already selected. Using a CTK file makes it easier to run the same task with the same settings over and over again.

All task files must be saved in the repository. For the Saved Task Repository, the data folder contains all of the CTM and CTK files that are used in this repository.

41

Access the Saved Task Repository in SAS Studio





a For the name of the repository, enter Saved Task Repository.

b For the URL of the repository, enter http://my-repository/Repository/tasks/repository.html.

c Click Add.


42 Chapter 6 / Saved Task Repository

In the navigation pane, click the Tasks and Utilities section to view the tasks in the Saved Task Repository.

Referencing CTM and CTK Task Files

In the Server Files and Folders section of the navigation pane, open the data/tasks.xml file. The tasks.xml file shows that this repository contains four tasks: List Data Model; List Data - SASHELP.FISH; List Data - SASHELP.GAS; and List Data - SASHELP.VOPTIONS.

The Template element specifies the location of each task file. This element accepts both CTM and CTK files.

<?xml version="1.0" encoding="UTF-8"?><Tasks>

<Task> <Name label="List Data Model"/> <Template uri="./ListData.ctm"/> </Task>

<Task> <Name label="List Data - SASHELP.FISH"/> <Template uri="./ListDataFish.ctk"/> <Icon uri="http://www.clipartbest.com/cliparts/pc5/kRR/pc5kRRBcB.png"/> </Task>

<Task> <Name label="List Data - SASHELP.GAS"/> <Template uri="./ListDataGas.ctk"/> </Task>

<Task> <Name label="List Data - SASHELP.VOPTIONS"/>

Referencing CTM and CTK Task Files 43

<Template uri="./ListDataOptions.ctk"/> <Documentation uri="http://www.ats.ucla.edu/stat/sas/library/nesug00/ bt3004.pdf" label="Introduction to Dictionary Tables"/> <Icon uri="./ListTable.png"/> </Task></Tasks>

Now, click the Tasks and Utilities section in the navigation pane. If you open the List Data Model task (which uses the ListData.ctm file), no data set is selected by default. Next, open the List Data - SASHELP.FISH task. When you open this task, the SASHELP.FISH data set is automatically selected. This data set is a setting in the ListDataFish.ctk file, so this data set is selected by default when you open the List Data - SASHELP.FISH task.


If you open the List Data - SASHELP.VOPTIONS task, you see that the SASHELP.VOPTION data set is selected and that the optname and setting columns are assigned to the List variables role. These settings are part of the

Referencing CTM and CTK Task Files 45

ListDataOptions.ctk file, so the data set and roles are already set when you open the List Data - SASHELP.VOPTIONS task.


Recommended Readingn SAS Studio: User's Guide

n SAS Studio: Administrator's Guide

For a complete list of SAS publications, go to sas.com/store/books. If you have questions about which titles you need, please contact a SAS Representative:

SAS BooksSAS Campus DriveCary, NC 27513-2414Phone: 1-800-727-0025Fax: 1-919-677-4444Email: [email protected] address: sas.com/store/books

47

http://sas.com/store/books

mailto:[email protected]

http://sas.com/store/books

48 Recommended Reading

Index

Special Characters

{baseURL} 32

C

categoriescreating 26

configuration properties 5CSV files 32CTK files 41CTM files 41

D

data files 32developing a repository 9documentation 30Documentation element 30

E

elementsDocumentation 30Icon 28

F

FILENAME statement, URL Access Method 35

filesrepository.html 21repository.xml 17snippets.xml 19tasks.xml 18

FTP shortcuts 13

G

global repositories 5

I

icons 28

M

Macro Repositoryaccessing in SAS Studio 36

O

Oracle VirtualBox 9

R

repositoriesabout 3accessing 3, 21accessing in SAS Studio 13components 17developing 9documentation 30editing 13file structure 17global 5icon 28simple 17snippets 25validating 21

Repository Toolkit Appliance 9configuring 11downloading 9importing 9

repository.html 21creating 21

repository.xml files 17

49

S

same-origin policy 17SAS macros 35

referencing from a task 36snippets 39

Saved Task Repositoryaccessing in SAS Studio 42

Simple Repository 17snippets

categories 26categorizing 19documentation 30icons 29referencing SAS macros 39

Snippets Repositoryaccessing in SAS Studio 25

snippets.xml files 19

T

taskscategorizing 18icons 29referencing a macro 36referencing CTK files 43referencing CTM files 43

tasks.xml files 18TXT files 32

X

XLS files 32

50 Index

sas studio 3...repository within sas studio. to change a global repository, an administrator or...

Documents