sas api macros 1.1 user’s...

SAS® Drug Development SAS API Macros 1.1User’s Guide

SAS® Documentation

SAS® Drug Development 4.2: Macros User’s Guide

Copyright © 2013, 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.

U.S. Government Restricted Rights Notice: Use, duplication, or disclosure of this software and related documentation by the U.S. government is subject to the Agreement with SAS Institute and the restrictions set forth in FAR 52.227-19, Commercial Computer Software-Restricted Rights (June 1987).

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

2nd electronic book, April 2013

SAS® Publishing provides a complete selection of books and electronic products to help customers use SAS software to its fullest potential. For more information about our e-books, e-learning products, CDs, and hard-copy books, visit the SAS Publishing Web site at support.sas.com/publishing or call 1-800-727-3228.

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 registered trademarks or trademarks of their respective companies.

iii

Contents

Chapter 1 Introduction ........................................................................... 1 Audience ............................................................................................................................. 1

Typographic and Syntax Conventions Used in This Guide ............................................ 1

Chapter 2 Installing the Macros .............................................................. 3 Overview ........................................................................................................................... 3

Requirements ................................................................................................................... 3

Installation Instructions for UNIX ................................................................................. 5

Verifying the Installation ................................................................................................ 6

Chapter 3 SAS® Drug Development Macros .......................................... 7 Introduction ...................................................................................................................... 8

Macro Return Codes .......................................................................................................... 9

The Macros ........................................................................................................................ 9

1

1 Introduction

Audience ......................................................................................................................................................... 1 Typographic Conventions Used in This Guide ............................................................................................. 1

Audience

This guide is intended for users who want to develop applications with the SAS Drug

Development macros.

You must be familiar with SAS Drug Development functionality, such as type

definitions, containers, files, and access permissions. For reference information on SAS

Drug Development functionality, see the SAS Drug Development online Help and user’s

guide.

Typographic Conventions Used in This Guide

Throughout this document you’ll see the following typographic conventions:

Convention Description

monospace font denotes code, such as a code example

monospace bold font denotes text that you type, such as an object name

monospace bold italics font denotes a value that you specify, such as your name

C H A P T E R

2 Typographic Conventions Used in This Guide Chapter 1

The following graphic explains the syntax for SAS code used in this document:

3

2 Installing the Macros

Overview ........................................................................................................................................................ 3 Requirements ................................................................................................................................................. 3 Installation Instructions for Microsoft Windows .......................................................................................... 3 Verifying the Installation .............................................................................................................................. 5

Overview

This document describes how to install the SAS Drug Development API Macros, which

are distributed in the sdd-sas-macro-1.1.zip.

Requirements

The following software is required by the SAS Drug Development Macros:

SAS 9.3+

Java Runtime Environment Version 1.6.0+

The corresponding version of the SAS Drug Development Remote API client

Installation Instructions for Microsoft Windows

1 Follow the instructions in the Getting Started with the SAS Drug Development

Java API doc to install the API client. Be sure to note the location of the lib

directory. Typically this would be:

C:\sdd-java-api-client-1.5\lib

2 Unzip the contents of sdd-sas-macro-1.1.zip to C:\.

This creates the following files and folders in C:\:

sdd-sas-macro-1.1\lib

This folder contains the sas.hls.drug.api.macro.jar

sdd-sas-macro-1.1\sasmacros

This is the folder that contains the SAS Drug Development macros as .sas

files.

3 Determine where you have SAS installed and where the config file is. In a typical

Windows English Language installation, !sasroot would point to:

C:\Program Files\SAS\SASFoundation\9.3\nls\en

C H A P T E R

4 Installation Instructions for Microsoft Windows Chapter 2

You need to edit the file !sasroot\sasv9.cfg and add the following lines near the

top, right before the comment box with the “WARNING:” label in it:

/* define the location of the SAS Drug Development API Macros */

-insert sasautos "C:\sdd-sas-macro-1.1\sasmacros"

/* put both the macro and api client jars on the classpath */

-JREOPTIONS (-Dsas.app.class.dirs=C:\sdd-sas-macro-1.1\lib;C:\sdd-java-api-

client-1.5\lib)

Caution: Back up this file before you edit it. Use extreme care when editing this file

and modify only these options. Ensure that you do not insert any carriage returns

in the sas.app.class.dirs option. If you have any questions, concerns, or

problems, contact your on-site SAS support personnel.

4 If you are connecting to an instance of SAS Drug Development that is hosted by

SAS, and you are behind a firewall and proxy servers, you might need to address

proxy requirements or restrictions.

If HTTPS traffic is proxied, specify the following Java system properties in the -

JREOPTIONS statement to configure the Java runtime environment:

-Dhttps.proxyHost=<proxy-host-name> -Dhttps.proxyPort=<port-number>

The -JREOPTIONS statement (when using a proxy server) will look similar to the

following when you are finished:

-JREOPTIONS=(

-Dsas.app.class.dirs=C:\sdd-sas-macro-1.1\lib;C:\sdd-java-api-client-1.5\lib

-Dhttps.proxyHost=yourProxyServer.sas.com

-Dhttps.proxyPort=8080)

5 Once you have made these changes to the sasv9.cfg file, save the file and start a

new SAS session.

Installing the Macros Verifying the Installation 5

Verifying the Installation

The following SAS code displays the settings for the JREOPTIONS and verifies that the

JRE is configured properly. It also verifies that the SAS Drug Development macros are

installed and functioning as expected. Replace sdd-instance, sdd-user-ID, and sdd-

password with values that reflect your instance of SAS Drug Development.

/* verify the JRE settings */

options mprint;

proc javainfo;

run;

/* initiate a connection to SAS Drug Development */

%sasdrugdev_login(sdd_url=%str(https://sdd-instance), sdd_userid=%str(sdd-user-ID),

sdd_password=%str(sdd-password)) ;

/* print information about the version of the API */

%sasdrugdev_getsddapiversion() ;

/* List the contents of the root folder in SDD */

%sasdrugdev_getchildren(sdd_path=%str(/SAS/Files)) ;

proc print;

title "List of Objects in /SAS/Files";

run;

/* terminate the connection to SAS Drug Development */

%sasdrugdev_logout() ;

The code should generate a list of the contents of the root folder in the SAS Drug

Development repository.

Note: By default, the root folder in the SAS Drug Development repository is /SAS. If the

root of your SAS Drug Development repository is different, change /SAS in the code

above.

The SAS log will contain information that might be useful for debugging the installation

of the SAS Drug Development macros.

https://sdd-instance/

6 Verifying the Installation Chapter 2

7

3 SAS® Drug Development Macros

Introduction ................................................................................................................................................... 8 Macro Return Codes ...................................................................................................................................... 8 The Macros..................................................................................................................................................... 9

Using the Ampersand Character (&) in URLs ...................................................................................... 9 The Proper Case for Parameter Values .................................................................................................. 9 SASDRUGDEV_COPY .......................................................................................................................... 9

Description ...................................................................................................................................... 9 Syntax ............................................................................................................................................. 9

SASDRUGDEV_CREATEFILE ............................................................................................................ 9 Description ...................................................................................................................................... 9 Syntax ............................................................................................................................................. 9

SASDRUGDEV_CREATEFOLDER .................................................................................................... 10 Description .................................................................................................................................... 10 Syntax ........................................................................................................................................... 10

SASDRUGDEV_DELETEOBJECT .................................................................................................... 10 Description .................................................................................................................................... 10 Syntax ........................................................................................................................................... 10

SASDRUGDEV_GETCHILDREN ...................................................................................................... 10 Description .................................................................................................................................... 10 Syntax ........................................................................................................................................... 11

SASDRUGDEV_GETCONTENTSOURCE ........................................................................................ 12 Description .................................................................................................................................... 12 Syntax ........................................................................................................................................... 12

SASDRUGDEV_GETSDDAPIVERSION ........................................................................................... 12 Description .................................................................................................................................... 12 Syntax ........................................................................................................................................... 12

SASDRUGDEV_GETVERSIONS ....................................................................................................... 13 Description .................................................................................................................................... 13 Syntax ........................................................................................................................................... 13

SASDRUGDEV_ISVERSIONED ........................................................................................................ 14 Description .................................................................................................................................... 14 Syntax ........................................................................................................................................... 14

SASDRUGDEV_LOGIN ...................................................................................................................... 14 Description .................................................................................................................................... 14 Syntax ........................................................................................................................................... 14

SASDRUGDEV_LOGOUT .................................................................................................................. 15 Description .................................................................................................................................... 15 Syntax ........................................................................................................................................... 15

SASDRUGDEV_OBJECTEXISTS...................................................................................................... 15 Description .................................................................................................................................... 15 Syntax ........................................................................................................................................... 15

SASDRUGDEV_UPDATEFILE .......................................................................................................... 15 Description .................................................................................................................................... 15 Syntax ........................................................................................................................................... 15

C H A P T E R

8 Macro Return Codes Chapter 3

Introduction The SAS Drug Development macros enable you to use familiar SAS syntax to make

calls to SAS Drug Development. Your SAS programming skills and these macros enable you to perform certain operations.

From a programming perspective, the folders and files in the SAS Drug Development repository are containers and files. The names of the macros use this naming convention.

Macro Return Codes After you execute a macro, the global variable _SDDRC_ contains the return code, and

the global variable _SDDMSG_ contains any additional information.

Here are the specific values that can be returned by a macro: _SDDRC_ Value Explanation

-99 There is no code -39 The target folder is invalid -38 The path is missing -37 The source equals the target. -36 The version setting is invalid -35 The local path does not exist -34 An invalid parameter was passed -33 A new entry was not created -32 The object was not versioned -30 There is an invalid recursion -29 There are multiple sessions -28 The content source is invalid -25 An entry exists -14 The user account could not be authenticated -10 The user account is invalid

-9 The group is invalid -8 An unexpected error was encountered -4 The node is invalid -3 The object type is invalid for this macro -2 No session exists -1 The session is no longer valid 0 The macro executed without error 1 The entity code is valid

Note: A macro always returns a code, but a macro does not necessarily return every one of these codes.

SAS® Drug Development Macros The Macros 9

The Macros

Using the Ampersand Character (&) in URLs For a macro with a parameter that specifies a URL, such as a macro that sets

properties, you cannot embed the ampersand character (&) in the URL. The ampersand character is a special character in SAS. If you embed an ampersand character, SAS will attempt to resolve the subsequent text as a macro variable.

The Proper Case for Parameter Values Although SAS is case insensitive, the parameter values passed by the SAS Drug

Development macros are case sensitive. This chapter presents the parameter values in the case that they must be passed to the macros.

SASDRUGDEV_COPY

Description Copies a file or folder to the specific target location. The copy of versioned files will

not be versioned. The children of the copied folder will also be copied to the new location in their original directory structure.

Syntax %SASDRUGDEV_COPY(SDD_SOURCE=sdd-source, SDD_TARGET=sdd-target);

sdd- source is the path (starting at the root) and name of the object in SAS Drug Development to be copied.

sdd-target is the path (starting at the root) in SAS Drug Development where the object is to be copied. The target folder must already exist.

SASDRUGDEV_CREATEFILE

Description Creates an object in the SAS Drug Development repository. All parent folders needed

to create the full path for the file will be created if they do not already exist.

Syntax %SASDRUGDEV_CREATEFILE(LOCAL_PATH=local-path, SDD_PATH=sdd-path <

SDD_VERSIONING=sdd-versioning, ,SDD_COMMENT=sdd_comment, SDD_VERSION=sdd- version>) ;

local-path is the absolute path and name of the file on the local computer.

10 The Macros Chapter 3

sdd-path is the path (starting at the root) and name of the content object to be created in the SAS Drug Development repository. The path may not be a container.

sdd_versioning is an optional text string to indicate whether an object being created in the repository should be versioned. The default behavior of the macro is to create a non-versioned object. Therefore, if this parameter is not provided for does not equal 1, the resulting repository object will not be versioned.

sdd-comment is an optional text string to be inserted as the comment for a versioned object in the repository. This option is ignored non-versioned objects in the repository.

sdd-version is an optional text string to indicate the version number to assign to an object being created in the repository. The value must be in the valid format including a decimal point. If provided, this option is ignored when creating non-versioned objects in the repository.

SASDRUGDEV_CREATEFOLDER

Description Creates a folder in the SAS Drug Development repository. All parent folders needed

to create the full path for the folder will be created if they do not already exist.

Syntax %SASDRUGDEV_CREATEFOLDER(SDD_PATH=sdd-path) ;

sdd-path is the path (starting at the root) of the folder to be created in the SAS Drug Development repository. The path must be a valid path structure.

SASDRUGDEV_DELETEOBJECT

Description Deletes a content object from the SAS Drug Development repository.

Syntax %SASDRUGDEV_DELETEOBJECT(SDD_PATH=sdd-path);

sdd-path is the path (starting at the root) and name of the content object in the SAS Drug Development repository to delete.

SASDRUGDEV_GETCHILDREN

Description Returns a SAS data set that contains the metadata for all of the objects within a

container object in the SAS Drug Development repository.


Syntax %SASDRUGDEV_GETCHILDREN(SDD_PATH=sdd-path

<SDD_RECURSIVE=recursion-level,SAS_DSNAME=SAS-data-set>);

sdd-path is the path (starting at the root) and name of the container object in the SAS Drug Development repository.

Recusion_level is the level of recursion, and valid values are 0, 1, or 2. Setting the parameter to 0 returns records for the input container only. Setting the parameter to 1 returns records for the container and all objects within the container, but not sub containers. Setting the parameter to 2 returns records for the input container, objects within the container, and all sub containers and objects. The default value is 0.

SAS-data-set is the name of a SAS data set to create that will contain the metadata for the objects. Specify SAS-data-set as libref.dataset. The default value is WORK.SDDGETCHILDREN.

The data set contains a row for each object in the container object and columns with the following names. The dataset will be sorted by path and then name within path.

name, which is the name of the object path, the path to the object without the object name fullPath, which is the fully qualified name of the object description, the description of the object isContainer, which is a numeric flag that indicates whether the object is a

container object (0=no, 1=yes) isVersioned, which is a numeric flag that indicates whether the object is

currently versioned (0=no, 1=yes) versionLabel, the label associated with this specific version isCheckedOut, which is a numeric flag that indicates whether the object is

currently checked out (0=no, 1=yes) isLocked which is a numeric flag that indicates whether the object is currently

locked (0=no, 1=yes) size, which is the size of the object in bytes represented as a string (will be 0 for

containers) contentType, which is the content or MIME type of object objectType, which describes the type of the object (folder, dataset, program,

etc.) createdBy, the userid that created the object createdOn, the full date and time the object was created represented as a String dateCreated, the date the object was created as a SAS Datetime format lastModifiedBy, the userid that last modified the object lastModifiedOn, the date the object was last modified represented as a String dateLastModified, the date the object was last modified as a SAS Datetime

format propsLastModifiedBy, the userid that last modified the properties for the object state, for an Analysis or Project object only stateComment, for Analysis or Project only isSigned, does the object have electronic signatures attached to it


SASDRUGDEV_GETCONTENTSOURCE

Description Returns the current setting for the Macro API content source (as set by

sasdrugdev_setcontentsource()). The value of the current setting is written to the log and also stored in the macro variable _sddContentSource_.

Syntax %SASDRUGDEV_GETCONTENTSOURCE() ;

SASDRUGDEV_GETSDDAPIVERSION

Description Reports the version and build number for the current SAS Drug Development client

API version. The value is printed in the SAS log.

Syntax %SASDRUGDEV_GETSDDAPIVERSION();


SASDRUGDEV_GETVERSIONS

Description Returns a SAS data set that contains the metadata for all of the versions of an object

within the SAS Drug Development repository.

Syntax %SASDRUGDEV_GETVERSIONS(SDD_PATH=sdd-path, SAS_DSNAME=SAS-data-

set>);

sdd-path is the path (starting at the root) and name of the object in the SAS Drug Development repository.

SAS-data-set is the name of a SAS data set to create that will contain the metadata for the versions. Specify SAS-data-set as libref.dataset. The default value is WORK.SDDGETVERSIONS.

The data set contains a row for each version of the object and columns with the following names. The most recent version will be the first observation in the dataset.

name, which is the name of the object path, the path to the object without the object name fullPath, which is the fully qualified name of the object description, the description of the object isContainer, which is a numeric flag that indicates whether the object is a

container object (0=no, 1=yes) isVersioned, which is a numeric flag that indicates whether the object is

currently versioned (0=no, 1=yes) versionLabel, the label associated with this specific version isCheckedOut, which is a numeric flag that indicates whether the object is

currently checked out (0=no, 1=yes) isLocked which is a numeric flag that indicates whether the object is currently

locked (0=no, 1=yes) size, which is the size of the object in bytes represented as a string (will be 0 for

containers) contentType, which is the content or MIME type of object objectType, which describes the type of the object (folder, dataset, program,

etc.) createdBy, the userid that created the object createdOn, the full date and time the object was created represented as a String dateCreated, the date the object was created as a SAS Datetime format lastModifiedBy, the userid that last modified the object lastModifiedOn, the date the object was last modified represented as a String dateLastModified, the date the object was last modified as a SAS Datetime

format propsLastModifiedBy, the userid that last modified the properties for the object state, for an Analysis or Project object only stateComment, for Analysis or Project only


isSigned, does the object have electronic signatures attached to it

SASDRUGDEV_ISVERSIONED

Description Returns a SAS macro variable _sddIsVersioned_ that contains a value of 1 when the

specified file in the repository has versioning enabled.

Syntax %SASDRUGDEV_ISVERSIONED(SDD_PATH=sdd-path);

sdd-path is the path (starting at the root) and name of the object in the SAS Drug Development repository

SASDRUGDEV_LOGIN

Description Creates a connection to the SAS Drug Development instance. This macro must be

called before any others in order to establish your SDD session.

Syntax %SASDRUGDEV_LOGIN(SDD_URL=url, SDD_USERID=user-ID,

SDD_PASSWORD=password) ;

url is the URL of the SAS Drug Development instance to use in the form https://sddname.sas.com.

user-ID is the SAS Drug Development ID for the user account.

Password is the SAS Drug Development password for the user account.

Note: The parameters passed to the login macro are often strings containing special characters which may cause problems when resolved by SAS. You will probably want to wrap each of the parameters in a SAS function call to prevent any issues.

For example:

Within SAS Drug Development, use the following: %sasdrugdev_login(sdd_url=%str(http://sddinstance),

Sdd_userid=%str(sdd-user-ID), Sdd_password=%str (sddpassword ));

Outside SAS Drug Development, use the following: %sasdrugdev_login(sdd_url=%str(https://sddinstance),

Sdd_userid=%str(sdd-user-ID), Sdd_password=%str (sddpassword ));


Note: Use of macros outside of SAS Drug Development requires HTTPS while inside of SAS Drug Development uses HTTP.

Or if your password may contain a “%” or “&”:

%sasdrugdev_login(sdd_url=%str(https://sddinstance), Sdd_userid=%str(sdd-user-ID), Sdd_password=%nrbquote(sddpassword ));

SASDRUGDEV_LOGOUT

Description Closes the open connection to SAS Drug Development. This should be the last macro

you call in any program.

Syntax %SASDRUGDEV_LOGOUT() ;

SASDRUGDEV_OBJECTEXISTS

Description Determines whether an object exists in the SDD Repository. A message will be

printed to the log stating the existence (or not) of the object and the macro variable _sddObjectExists_ will be set to 1 if the object exists, 0 if it does not.

Syntax %SASDRUGDEV_OBJECTEXISTS(SDD_PATH =sdd-path);

sdd-path is the path (starting at the root) and name of the content object in the SAS Drug Development repository. This can be either a file or a container.

SASDRUGDEV_UPDATEFILE

Description Updates the contents of an existing object in the SAS Drug Development repository.

If the object has versioning enabled, a new minor version of the object will be created. If the object is not being versioned, the existing contents will be replaced.

Syntax %SASDRUGDEV_UPDATEFILE(LOCAL_PATH=local-path, SDD_PATH=sdd-path <,

SDD_COMMENT=sdd-comment>, SDD_VERSION=sdd-version-type) ;


local-path is the absolute path and name of the file on the local computer.

sdd-path is the path (starting at the root) and name of the content object in the SAS Drug Development repository to update. The object must already exist and may not be a container.

sdd-comment is an optional text string to be inserted as the comment for a versioned file in the repository. This value is ignored for non-versioned objects.

sdd-version-type is an optional text string to designate the type of version to be created if the object to be updated has versioning enabled. Valid values are MAJOR or MINOR. The default is MINOR. This value is ignored for non-versioned objects.

sas api macros 1.1 user’s...

Documents