SAS/AF Software Procedure Guide

AF Command

Use the AF command to execute applications that have been created with the BUILD procedure in SAS/AF software.

Note: The AF command can execute entry types that provide a display (CBT, FRAME, HELP, MENU, or PROGRAM), as well as SCL entries that execute without a display. The other SAS/AF catalog entry types are not executable and cannot be executed with the AF command. [cautionend]

You can issue the AF command from any SAS window. Only one application that is invoked by the AF command can be active at a time. If you issue an AF command while another application is already running, the previous application is closed before the new application is executed. To run additional SAS/AF applications simultaneously, use the AFAPPLICATION command instead. See AFAPPLICATION Command for details.

Syntax

The general form of the AF command is

Requirement

The first time you use the AF command, you must use the CATALOG= argument to identify the application to execute. The name of the entry at which an application starts executing is recorded in the special AF.AFGO entry in your SASUSER.PROFILE catalog. This entry is referred to as the AF checkpoint. Any subsequent AF command that does not include the CATALOG= argument starts at the entry identified in the AF checkpoint. The AF checkpoint is retained across SAS sessions.

Note: If you exit an application from a CBT entry, the name of the CBT entry from which you exit the application is stored as the AF checkpoint rather than the name of the initial entry in the application. This enables you to resume CBT applications at the point where you stopped. Use the CHECKLAST=NO option to override this default behavior and to store the name of the initial entry even when exiting from CBT entries. [cautionend]

Options

For most of the following AF command options, there is a default action if you do not use the option. You should use an option only when you want to change the default behavior.

AUTORECALL=YES|NO

specifies whether field values that have been saved from a previous invocation of a PROGRAM entry are recalled when the entry is invoked again. By default, field values are not recalled (AUTORECALL=NO). Use AUTORECALL=YES if you want the stored field values to be recalled. Stored values are available only if the entry has previously been closed while the AUTOSAVE=YES option was in effect.

Note: The AUTORECALL= option only affects the behavior of PROGRAM entries. [cautionend]

AUTOSAVE=YES|NO

specifies whether the values in the fields of PROGRAM entries are saved when you exit from an entry. By default, field values are not saved (AUTOSAVE=NO). Use AUTOSAVE=YES to store all current field values when you close a PROGRAM entry. You can use the AUTORECALL=YES option to recall these values the next time the entry is invoked.

Note: The AUTOSAVE= option only affects the behavior of PROGRAM entries. [cautionend]

AUTOTERM=YES|NO|VERBOSE|NOVERBOSE

specifies whether the _term method of FRAME entry objects is automatically executed if the objects still exist when the entry ends. By default, any open objects are automatically terminated (AUTOTERM=YES). Use AUTOTERM=NO if you want to prevent the _term method of open FRAME objects from being executed when the entry ends.

By default, no list of open objects is generated (AUTOTERM=NOVERBOSE). Use AUTOTERM=VERBOSE to print to the SAS log a note containing the object list for each object that still exists when the entry ends. This feature works even if automatic object termination is off, and it serves as a debugging aid to identify objects whose _term method has not run.

You cannot combine options in one string. Instead, use a separate AUTOTERM= option with the AF or AFAPPLICATION command. For example:

af c=mylib.cat.primary.frame autoterm=verbose autoterm=yes

Note: The AUTOTERM= option only affects the behavior of FRAME entries. [cautionend]

AWS=YES|NO|KEEP

specifies whether the application's windows are confined to a container window called the application workspace (AWS). When an application workspace is used, you can minimize or maximize the entire application by minimizing or maximizing the AWS window.

Note: The AWS= option is ignored if your host environment does not support application workspaces. [cautionend]

Specify one of the following values for the AWS= option:

YES opens all windows displayed by the AF application (including windows displayed by the CALL DISPLAY routine) within the single AWS window. This is the default behavior unless it is overridden by a host-specific resource.

NO opens each entry in an application in its own window rather than in the AWS window.

KEEP keeps the application workspace open after the last window in the workspace is removed. This prevents the AWS from being deleted during situations such as unconditional branching in CBT entries or using CALL GOTO routines in SCL programs. In these situations, all the current windows for the application are closed before other windows are opened.

CATALOG=libref.catalog-name.entry-name.entry-type CAT=libref.catalog-name.entry-name.entry-type C=libref.catalog-name.entry-name.entry-type

specifies the name and type of the SAS catalog entry at which an application starts executing. You must specify a complete four-level name. You must include this argument the first time you use the AF command.

If you omit the CATALOG= option, the AF command starts the entry that is identified as your AF checkpoint in the SASUSER.PROFILE.AF.AFGO entry. If the application starts executing at a FRAME, PROGRAM, MENU, or HELP entry, then the name of the initial entry is identified in the AF checkpoint. If you exit the application from a CBT entry, then the CBT entry from which you exit is identified as the AF checkpoint.

CATNAME=libref.catref (libref.catalog-1 ... libref.catalog-n)

logically combines two or more catalogs into one by associating them with a catref (a shortcut name). You can use any valid SAS name for catref, but if you use the name of an existing catalog you will not be able to access the contents of that catalog until the catref is cleared. The libref that you specify with the catref must already exist. Enclose the list of catalogs in parentheses, and use blanks to separate the catalog names in the list.

When a program in the SAS/AF application contains a reference to an entry in the libref.catref catalog, the AF task searches for the entry in the specified list of catalogs, starting with catalog-1 and ending with catalog-n.

For example, suppose that you open an application with

af cat=mylib.mycat.main.frame
   catname=mylib.all (mylib.apps1 mylib.apps2 master.apps)

A reference in a program to MYLIB.ALL.TEST.SCL causes the AF task to search for MYLIB.APPS1.TEST.SCL, then for MYLIB.APPS2.TEST.SCL, and finally for MASTER.APPS.TEST.SCL.

Refer to the description of the CATNAME statement in SAS Language Reference: Dictionary for more information about creating and using catrefs. You can also create and clear catrefs by using the CATNAME command in AF windows. See the description of the CATNAME command in Window Management Commands for details.

CHECKLAST=YES|NO CHECK=YES|NO

specifies whether the system stores the name of the CBT entry at which you exit an application. By default, the name of the current entry is stored as the AF checkpoint when you exit an application from a CBT entry (CHECKLAST=YES). The AF checkpoint identifies the application that runs when you issue an AF command without using a CATALOG= argument. Use CHECKLAST=NO to record the name of the initial entry for the application instead, so that the CBT application resumes at the beginning rather than at the entry where you stopped.

Note: The CHECKLAST= option only affects the behavior of CBT entries. [cautionend]

DEBUG=YES|NO

specifies whether the SCL source-level debugger runs on an application's programs. By default, the debugger is not activated (DEBUG=NO). Use DEBUG=YES to activate the debugger.

Note: In order to analyze programs with the SCL debugger, the programs must be compiled with the compiler's DEBUG ON option. [cautionend]

The SCL debugger can interactively monitor the execution of SAS/AF applications. It enables you to track down logical errors while the program executes. The debugger displays the source program, specifies which line is executing, and dynamically watches the values of variables. It also enables you to suspend an executing program that is part of a nested series of programs and to execute other programs in the series. For more information about the SCL debugger, see SAS Component Language: Reference.

FRAME=frame-number|frame-name

specifies the starting frame for a CBT application. Identify the starting frame by using either of the following:

the frame number. To determine the number of a frame in a CBT entry, use the ID command when that frame is displayed.
the frame name, which is the name specified in the NAME= option on the frame delimiter line. This method is more efficient because the AF command can remain the same even if the number of frames changes.

For testing CBT applications, the FRAME= option provides a convenient way to return directly to a specific frame in the system. It is also useful for indexing a CBT course that contains multiple topics.

Note: The FRAME= option only affects the behavior of CBT entries. [cautionend]

ICON=icon-number

specifies the number of the icon that is used to represent an AWS window when the window is minimized. By default, the SAS/AF icon is displayed.

Note: This option has an effect only if the native windowing system supports application workspaces and you also use the AWS=YES option. [cautionend]

LABEL=label

specifies the name of an SCL program label where execution begins when the AF command is used to execute a stand-alone SCL entry. Execution begins at the specified label and continues until a RETURN statement is reached.

Note: The LABEL= option only affects the behavior of SCL entries. [cautionend]

PMENU=YES|NO

specifies whether the PMENU facility can be turned off in an application. By default, users can issue the PMENU OFF command to turn off menus in the application (PMENU=NO). Use PMENU=YES if you have customized the menus in your windows and want to ensure that users cannot turn the PMENU facility off for windows in your application.

If your SAS/AF application invokes additional applications by issuing an AF or AFAPPLICATION command with the EXECCMD routine, include the PMENU=YES option in the command if you want the additional applications to have the same behavior.

RESIDENT=number

specifies the number of SCL entries that are kept resident in memory after they are read from the catalog. Entries can be read from memory much more quickly than from the catalog, so keeping frequently used SCL entries in memory improves the performance of SAS/AF applications.

When an SCL entry is invoked, the AF task searches resident memory for the entry. If the search is successful, the entry moves to the top of the search list. An SCL entry that is called frequently remains at or near the top of the list and so is found more quickly. If the SCL entry is not found in the search list, it is read from the catalog and inserted at the top of the list. If the maximum number of entries are already resident, then the last entry in the search list (the least-recently used) is removed to make room for the new entry.

By default, 64 SCL entries are saved in memory. The number value is interpreted as follows:

0 No SCL entries are kept in memory. All SCL entries must be read from the catalog each time they are called.

> 0 The specified number of entries are kept in memory.

RESTART=YES

specifies whether CBT entries are restarted from the beginning. By default, a CBT entry starts at the CBT frame that was last accessed (RESTART=NO). Use RESTART=YES if you want to ensure that the CBT entry starts at the first frame.

Note: The RESTART= option only affects the behavior of CBT entries. [cautionend]

SCLPROF=COVERAGE|TIMER

starts the data collection phase for the specified diagnostic tool.

COVERAGE

starts data collection for the Coverage Analyzer tool. The Coverage Analyzer can uncover gaps in your interactive applications testing by identifying which lines in an application are not executed during a test session. When you end the application that was started by the AF command, the SCL Coverage Analyzer window opens to present the results of the analysis. Refer to the online Help for the Coverage Analyzer for more information on using this diagnostic tool.

TIMER

starts data collection for the Performance Analyzer tool. The Performance Analyzer provides timing and frequency statistics for each entry, label, and function call that is executed in an application's SCL code. It also provides a hierarchical view of the execution sequence for the application. When you end the application that was started by the AF command, the SCL Performance Analyzer window opens to present the results of the analysis. Refer to the online Help for the Performance Analyzer for more information on using this diagnostic tool.

TITLE='title'

specifies a title for the AWS window. If the title contains embedded blanks, enclose it in single quotes, as in the following example:

af c=corp.fin.inv.program title='Inventory Analysis'

Note: The TITLE= option has an effect only if the native windowing system supports application workspaces and you also use the AWS=YES option. [cautionend]

application-options

are options for the application that is being invoked by the AF command. These options are handled differently, depending on which entry type is being invoked.

For FRAME, PROGRAM, or SCL entries, values are passed to the entry in the SCL list _CMDLIST_, which is a sublist of the local environment list. See Passing Options to an Application for details.
For CBT entries, values specified following the AF command options cause the AF task to search the entry's initial frame for a feedback indicator line that has a matching MENU=value option. If a match is found, the CBT frame specified in the line's FRAME= option is displayed.
For example, the following command causes the AF task to search the first frame of the entry USING.CBT for a feedback indicator line that contains the option MENU=HELLO:
```
af c=company.sales.using.cbt hello
```
If a matching option is found, the AF task branches to the CBT frame that is specified in the line's FRAME= option. If no matching MENU= option is found, then the HELLO argument is ignored.
For MENU entries, values that follow the AF command options are matched with that menu's selection options.
For example, the following command causes the AF task to search the MAIN.MENU entry for a selection option named HELLO:
```
af c=company.sales.main.menu hello
```
If the specified option exists, the AF task branches to the entry that is invoked by the selection option. If HELLO is not a valid selection, the AF task displays the following message:
```
Warning: no HELLO selection for this menu
```
You can also specify an option number on the primary menu or on submenus. To specify option numbers for submenus, separate the option numbers by periods. For example, you can specify 3.2 to display the entry called by choice 2 from the submenu that is called by choice 3 of the main menu.
For HELP entries, values that follow the AF command options are ignored.

Using the AF Command

For entry types that provide a display (CBT, FRAME, HELP, MENU, and PROGRAM), the AF command opens the specified entry in an AF window. You can use SAS windowing environment commands while executing applications in the AF window, including commands that move, resize, and change the windows. However, window sizes and colors cannot be saved. Window properties are determined permanently when an application is designed. See AF Window Commands for information about other commands that are supported in the AF window.

You can also use the AF command to execute SCL entries. In this case, the SAS Component Language code in the entry is executed without opening a display window.

Chapter Contents
Previous
Next
Top of Page

YES	opens all windows displayed by the AF application (including windows displayed by the CALL DISPLAY routine) within the single AWS window. This is the default behavior unless it is overridden by a host-specific resource.
NO	opens each entry in an application in its own window rather than in the AWS window.
KEEP	keeps the application workspace open after the last window in the workspace is removed. This prevents the AWS from being deleted during situations such as unconditional branching in CBT entries or using CALL GOTO routines in SCL programs. In these situations, all the current windows for the application are closed before other windows are opened.

0	No SCL entries are kept in memory. All SCL entries must be read from the catalog each time they are called.
> 0	The specified number of entries are kept in memory.