Passing Options to an Application

Introduction

The AF and AFAPPLICATION commands can pass option values to your FRAME, PROGRAM, and SCL applications. The general form for application options is

<option-name=>option-value <... <option-name-n=>option-value-n>

For example, if you design an application that requires a list of observation numbers as input, you can invoke the application with the following AF command:

af c=master.apps.obs.scl obs=17 23 19 47

The AF task stores the specified options and their values in a special list called _CMDLIST_. This list is a sublist of the SCL local environment list that is created when a SAS/AF application is invoked.

If the option is specified in the form name=value (for example, OBS=17), then both the name and the value are stored in the list; otherwise just the value (for example, 23 or 19) is stored. In this case value is a number. However, it also can be one of the following:

an unquoted text string such as YES or NO
a quoted text string such as 'Apply SAS Software'
a hexadecimal string such as '534153'x
a date, time, or datetime literal such as '19Jun1991'D.

If you want several words to be treated as one argument, you must enclose them in quotes.

You can use the list manipulation functions in SAS Component Language to extract the option values and to use them in your applications. Refer to the SAS Component Language: Reference for information about SCL list functions.

Values That Are Automatically Placed in the Command List

The library, catalog name, entry name, and entry type values are automatically added to the command list. (If you omit the CATALOG= option in the AF command, the application name is retrieved from the SASUSER.PROFILE.AF.AFGO catalog entry.) Therefore, the command list is always at least four items long. For example, suppose you issue the following command:

af c=training.sas.intro.program

For this command, the _CMDLIST_ list contains the following values:

_CMDLIST_=(LIBNAME='TRAINING'
           CATALOG='SAS'
           NAME='INTRO'
           TYPE='PROGRAM'
           )

Differences in Storing AF Command and Application-specific Options

The rules for storing the values of application-specific options in the _CMDLIST_ list are somewhat different than for AF command options, as explained in the following table:

Comparison of Option Value Handling
Values	For AF command options	For application-specific options
Options repeated in the same AF command	are ignored except for the last occurrence, which is stored in the command list	are all stored in the command list
Abbreviations specified for YES and NO values	are stored in the command list as YES and NO (the abbreviations are expanded and converted to uppercase)	are stored in the command list exactly as specified
Values specified in lowercase	are converted to uppercase unless quoted	are stored in the command list in lowercase

For example, suppose you issue the following AF command:

af c=a.b.c.program check=y check=n

For this command, the _CMDLIST_ list contains the following values:

_CMDLIST_=(LIBNAME='A'
           CATALOG='B'
           NAME='C'
           TYPE='PROGRAM'
           CHECKLAST='NO'
           )

Notice that the CHECKLAST= option appears only once in the command list, reflecting the last occurrence of the CHECK= option in the AF command. (The short form of the option name is expanded to its full form.)

However, suppose you enter the following command:

af c=a.b.c  name='David S.' Obs=17 23 19 term=y term=n

For this command, the _CMDLIST_ list contains the following values:

_CMDLIST_=(LIBNAME='A'
           CATALOG='B'
           NAME='C'
           TYPE='PROGRAM'
           NAME='David S.'
           OBS=17
           23
           19
           TERM='y'
           TERM='n'
           )

The application-specific NAME= option does not conflict with the NAME= option generated by the AF command that contains the current entry name.

Using Command Macros

If your application accepts options, you can design a command macro to invoke the application. For example, suppose you create an entry named FINANCE.REPORTS.GENRPT.SCL that accepts the following options:

TITLE=“title-text”
DATE=SAS-date-value

You can create the following command macro to invoke the application:

%macro genrpt(title="Financial Report",date=0)/cmd;
   afapp c=finance.reports.genrpt.scl title=&title date=&date
%mend genrpt;

Then, users can invoke the application with the GENRPT command, provided the macro is loaded in the current SAS session and the CMDMAC system option is specified. If a user issues the genrpt command with no arguments, then the SCL entry is executed with the default title and date. However, a user can specify a different title and date. For example, a user can issue the following command:

genrpt date='24Jul1999'D title="Personnel Report"

The SAS macro facility changes that command into the following command:

afapp c=finance.reports.genrpt.scl
      title="Personnel Report" date='24Jul1999'D