SAS Explorer Actions

by Richard A. DeVenezia View Comments Send Feedback

This document describes the functioning of the SAS Explorer window, the details of customization and strategies for managing customizations. This article is the basis of my paper "SAS® Explorer: Use and Customization" presented at NESUG 2005.

If you know all about SAS Explorer, proceed to action sets

SAS Explorer

Windows

The SAS Explorer lets you explore the hierarchies of your SAS environment using the explorer motif (a left pane tree view for hierarchy and a right pane list view for details). The tree pane can be hidden by using a View menu choice or the Toggle tree toolbar icon. Of prinicipal interest, in order of descent, are SAS libraries, members and entries.

Active libraries

The details pane displays the libnames that are currently assigned. Each item listed has a one-level name, libname. The items are displayed in one of four selectable modes: Large Icons, Small Icons, List and Details. When in details mode, the items can be sorted by Name, Engine, Type or Host Path Name. Sort by clicking on a column header, click again to reverse the sort order.

Contents of libname

The details pane displays the members of a libname. The members shown are items such as tables, views and catalogs. Each item has a two-level name, libname.memname. The items are displayed in one of four selectable modes: Large Icons, Small Icons, List and Details. When in details mode, the items can be sorted by Name, Type, Size, Description or Modified date. Sort by clicking on a column header, click again to reverse the sort order.

Contents of catalog

The details pane displays the entries of a catalog. There are a large number of entry types, at least 60! Some common types are source, log, output, frame, scl, class. Each item has a four-level name, libname.memname.objname.objtype. The items are displayed in one of four selectable modes: Large Icons, Small Icons, List and Details. When in details mode, the items can be sorted by Name, Type, Description, Size or Modified date. Sort by clicking on a column header, click again to reverse the sort order.

Menus

When an item in a list is right clicked a context menu appears.

You have now reached base camp for climbing the Everest of extending SAS Explorer.

SAS Explorer Options

The SAS Explorer has a huge untapped capability. Every selectable member and entry type can have customized context menu choices. The mouseful way to create customized choices is to click in a SAS Explorer window and select menu Tools/Options/Explorer... This raises the Explorer Options... dialog window. For the command-centric, issue command EXPOPTS.

Options for library members.

Options for catalog entries.

SAS Online help discusses this dialog. In the table of contents, drill down:
SAS Products
Base SAS
Using Base SAS Software
Using the SAS Windowing Environment
Using the Explorer Window
Using the Explorer Options Window
Follow the link to "Changing the Pop-Up Actions and Icon for a Registered Type"

SAS Explorer and the settings of the Explorer Options dialog interact in a manner very similar to Windows Explorer and its Tools/Folder Options dialog, File Types tab. You select a type and then edit it.
A list of actions for the type is displayed; you can add new ones, and edit or delete current ones. Each action has an Action and an Action Command. The action command is one or more SAS commands, and may interoperate with the macro system as well.

Making the connection

Replacement

When you select an item, and open the context menu by clicking the right mouse button, the parts of the item name are available to the action command. The manner in which they are available is a little unusual. Each % symbol in an action command is replaced with a name part in sequence. You must also specify how many bytes of the namepart to use.

The number between a % and b specifies how many bytes of the name part are used in the replacement. If you mistakenly used %1b for the libname namepart, your action command would only see the first letter of the library name! The number between a % and b may seem extraneous, but it is not. Although not required per se, it is a good idea to have then number so as to remind you which name part is supposed to be getting placed where. I have seen cases when the lack of a number caused part of a command to be 'eaten' by some internal processor. Case in point POSTMESSAGE "(%b,%b,%b,%b)", in version 8. Go numberless at your own risk.

Simple commands

The first step up from base camp is using simple task orientated commands that accept a SAS named thing as an argument.

Consider this action command for a library member of type data or view:

Example: for item sashelp.class the command gets resolved to:

FSVIEW sashelp.class

Using macro

The macro system can be used in an action command. Recall that a single % is used as a token for replacement with a namepart. But % is pretty darn important to macro too!

Use two % in an action command to indicate macro processing.

Consider this action command for a catalog entry:

Example: for item sashelp.devices.pscolor.dev the command gets resolved to:

%put sashelp.devices.pscolor.dev

Now don't get all excited about somehow crashing SAS with this. When you specify more bytes than a namepart has, SAS will not grab unknown characters from 'beyond' namepart. However, if you accidently specify a number of bytes less than a namepart has, you can truncate a namepart, which would cause problems for you.

Using DATA or Proc steps

GSUBMIT is a command for submitting SAS code snippets.

Consider this action command for a catalog entry:

Example: for item sashelp.devices.pscolor.dev the code submitted by resolving the command is:

data _null_;
put "sashelp.devices.pscolor.dev";
run;

Using SAS/AF Frames or SCL

The AFA command launches SAS/AF programs. Parameters are passed to the programs using name=value pairs on the command line.

Consider this action command for a catalog entry:

Example: for item sashelp.devices.pscolor.dev the code submitted by resolving the command is:

afa c=sasuser.myhandlers.foo.scl entry=sashelp.devices.pscolor.dev

The AFA command executor parses name=value pairs on the command line and stores the value as a named item in the _CMDLIST_ sublist of the local environment list. This sample SCL demonstrates how to obtain an arguments value.

declare char VALUE NAME='entry' ;

VALUE
  = getNitemC
    ( getNitemL
      ( envlist('L'), '_CMDLIST_' )
    , NAME, 1, 1, ''
    );

put NAME= VALUE=;

WARNING: The _CMDLIST_ reserves items of name LIBNAME, CATALOG, NAME and TYPE for it's own use. Do not use these names as parameter names in an AFA command.

An examination of the registry shows the AFA command is one favored by SAS Institute. Several actions are implemented by SCL entries in the catalog SASHELP.EXPLORER. These entries include source and demonstrate a range of features than can be used in implementing an action.

Using autocall macros

You can use auto macros to offload the code writing part of the action commands to a text file. This approach is recommended for situations when SAS/AF development is infeasible; perhaps due to SAS/AF not being licensed, or that available programming skills are in Base SAS and SAS Macro.

Consider this scheme; create a text file xactmac.sas. This file resides in a library specified in the SASAUTOS System Option. The file is constructed as such:

%macro xactmac (type,action,lib,mem,obj,typ);
  /* %xactmac will cause this file to be automatically included once,
   * and by side effect all the action_* macros will get compiled
   */

  /* dispatch typed action handler */
  %action_&type._&action (&lib,&mem,&obj,&typ);
%mend;

%macro action_data_fsview (lib,mem);
  fsview &lib..&mem;
%mend;

xactmac.sas might contains tens if not hundreds of macro declarations. For consistency, each macro would be named according to the construct action_{type}_{action}

When it comes time to entering an action command, a macro call is indicated.

The %xactmac call will forward resolution to %action_data_fsview.

Programmatic customization

The discussion up to this point only covers adding an action using the point and click dialog. This is ok for one or two actions, but what happens if you have dozens of actions to configure, and you want to reuse them in new projects or share them with coworkers or a programming community?

The SAS Explorer Options dialog is a front end for adding or updating keys in the SAS Registry. The keys that get altered by the dialog are under these branches:

CORE\EXPLORER\MENUS\MEMBERS
CORE\EXPLORER\MENUS\ENTRIES
CORE\EXPLORER\MENUS\FILES
CORE\EXPLORER\MENUS\METAEXPLORE\TypeFilters

There are three ways to alter the SAS Registry.

• Explorer Options dialog
• Proc REGISTRY
• SAS/AF class sashelp.fsp.registry.class

Proc REGISTRY

There is a moderate amount of information about Proc REGISTRY available in the Online Help. Read it. You will come to understand that values are loaded into the registry by creating a file that is constructed as such

[key]
"value-name"="value-content"

The keys of interest for customizing actions are

[CORE\EXPLORER\MENUS\MEMBERS\MEMBERTYPE]
[CORE\EXPLORER\MENUS\ENTRIES\ENTRYTYPE]
[CORE\EXPLORER\MENUS\FILES\FILETYPE]

plus

[CORE\EXPLORER\MENUS\MEMBERS\ROOT]
[CORE\EXPLORER\MENUS\MEMBERS\LIBRARIES]

The construct of the value-name is also important (and partly undocumented.)

• An ampersand, &, can precede your desired single letter mnemonic (aka shortcut key.)
• The form {A};{B} has several interpretations. {A} is a positional value, {B} is the menu text.
  If {A} starts with a minus sign, the item will be grayed.
  If {B} starts with a minus sign, the item will not appear in the menu (and may screw up the whole menu scheme for that entry or member type!)
• The form {A};{B};{C} has an additional interpretation.
  {C} can specify a classifier. The classifier controls what icon is displayed next to the menu choice.
  The list of classifiers are found at key [CORE\CLASSIFIERS]
  The icon appears only if {B} has a mnemonic!

Foo - Foo choice
&Foo - The key F will select the Foo choice, F will be underlined
10;&Foo - The Foo choice will appear after farther down the list
10;&Foo;100 - The Foo choice will have classifier icon 'CopyItem' next to it.

Advanced customizers might also use key

[CORE\EXPLORER\NEW\ENTRY\ENTRYTYPE]
[CORE\EXPLORER\NEW\MEMBER\ENTRYTYPE]

to alter the list of entry types shown in the New Entry dialog raised by selecting New from the context menu displayed when SAS Explorer is displaying the members of a library or contents of a catalog.

More on Macros

Macros - Part II.A

Suppose you named your action_* macros to exactly match the key path under which the command action is supposed to be installed. Further suppose the macros description corresponds to the menu choice you want displayed.

%macro action_members_table_A1 (lib,mem) / des='FS Browse';
  fsbrowse &lib..&mem sasuser.&lib..&mem..screen;
%mend;

Such a construct has all the information needed for a self realizing scheme. A program can read the macro catalog and write a file that Proc REGISTRY can import.

/ *
  * Register SAS Explorer actions based on macro name and description
  */

proc sql;
  create view actions as
  select *
  from dictionary.catalogs
  where libname = 'WORK'
    and memname = 'SASMACR'
    and objname like 'ACTION_%'
    and objtype = 'MACRO'
  ;
quit;

filename xact catalog 'work.explorer.actions.source';

data _null_;
  set actions;

  branch = scan (objname,2,'_');
  type   = scan (objname,3,'_');

  namevalue = quote(trim(objdesc));

  file xact;

  put '[CORE\EXPLORER\MENUS\' branch +(-1) '\' type +(-1) ']';
  put namevalue +(-1) '="%%' objname '(%8b,%32b,%32b,%8b)"';
run;

proc registry import=xact;
run;

Macros - Part II.B

A slightly different construct would use shorter macro names and place all action context info in the description:

%macro xact_1 (lib, mem) / des='M|TABLE|10;FS View';
fsview &lib..&mem; formula
%mend;

/*
 * Register SAS Explorer actions based on macro name and description
 */

proc sql;
  create view actions as
  select *
  from dictionary.catalogs
  where libname = 'WORK'
    and memname = 'SASMACR'
    and index (objname,'XACT_') = 1
    and objtype = 'MACRO'
  ;
quit;

filename xact catalog 'work.explorer.actions.source';

data _null_;
  set actions;

  branch  = scan (objdesc,1,'|');
  type    = scan (objdesc,2,'|');
  choice  = scan (objdesc,3,'|');

  if branch = 'M' then branch = 'MEMBERS'; else
  if branch = 'E' then branch = 'ENTRIES';

  select;
    when (branch =: 'M') command = '%%' || objname || '(%8b,%32b)';
    when (branch =: 'E') command = '%%' || objname || '(%8b,%32b,%32b,%8b)';
    otherwise delete;
  end;

  choice  = quote(trim(choice));
  command = quote(trim(objdesc));

  file xact;

  put '[CORE\EXPLORER\MENUS\' branch +(-1) '\' type +(-1) ']';
  put choice +(-1) '="%%' objname '(%8b,%32b,%32b,%8b)"';
run;

proc registry import=xact;
run;

Macros - Part II.C

A third variant would store a minimum of meta information in name or description. The minimum is the form of the macros invocation. The remainder of the meta information of the macros use context would be divulged upon request.

%macro xact_1 (lib, mem, divulge=) / des='%8b,%32b';
  %let divulge = %upcase(&divulge);
  %if &divulge = BRANCHES %then %do;
    MEMBERS\TABLE
    MEMBERS\VIEW
  %end;
  %else
  %if &divulge = NAME %then %do;
    %str(10;FS View)
  %end;
  %else %do;
    fsview &lib..&mem; formula
  %end;
%mend;

The benefit of this approach is that a single macro can indicate its utilization in more than context menu. The program to utilize divulgent macros whose names start with XACT is left as an exercise for the reader. The program would have to loop through the BRANCHES divulged and create a registry key entry for each. The two earlier approaches allow a macro to specify its applicability to only one branch.

Bonus section

Comments

Lines that start with the # symbol can be used to comment and document your registry import files.

# Purpose:     List the value mappings that comprise a numeric format
# Note:        The format must reside in a catalog listed
#              in the FMTSEARCH system option
# Contributor: Richard A. DeVenezia
# Date:        23Jan2005

[CORE\EXPLORER\MENUS\ENTRIES\FORMAT]
...

Name part specifiers

Experimentation shows the %nb tokens used for replacement are in fact format specifiers as used in the C function sprintf. The b Type is not standard; it is speculated to be a custom type implemented by SAS which stops output at width, or the first zero byte or blank. If you are curious, try using a specifier such as %x or %d.

The SAS Explorer maintains 2 (or 4) pointers that reference the memory locations where the nameparts are stored. When it is time to resolve the action command, something like this probably happens internally:

...obtain pointers to nameparts
...obtain action command from regigstry
sprintf ( lpstrCommand
        , lpstrActionCommand
        , lpstrLibname
        , lpstrMemname
        , lpstrObjname
        , lpstrObjtype);
...present lpstrCommand to command executor...

Richard A. DeVenezia