SAS/AF Catalog Entry Types

PROGRAM Entries

PROGRAM entries store SAS/AF applications that consist of

a display that provides instructions and data-entry fields and which accepts user input
general attributes that control the appearance and behavior of the window in which the PROGRAM entry executes
field attributes that define the appearance and behavior of fields
a SAS Component Language (SCL) program that controls the application.

The following sections describe each of these components of a PROGRAM entry.

You use the BUILD procedure's DISPLAY window to design the displays for PROGRAM entries. The displays can use any of the text color features and highlighting features that the SAS text editor supports. In addition to static text, the display can include fields in which users can enter values. The PROGRAM entry's SCL program can also manipulate field values. Refer to Fields for more information about defining fields in the display.

If your display includes a large amount of text or many fields, you can divide it into units called frames. Users can issue FORWARD and BACKWARD commands in the application window to scroll between the frames of the display. To divide the display into frames, enter divider lines consisting of dash (-) characters across the full width of the DISPLAY window. You can also use the FILL command to create divider lines.

You can designate a portion of the display that remains visible and does not scroll. Enter three caret (^) or NOT (¬) characters in the first three columns of a line in the first frame of the display to delineate the nonscrolling region. Any text and fields above the line that contains the ^^^ or ¬¬¬ appear in every frame of the display; FORWARD and BACKWARD commands scroll only the region below the nonscrolling area.

You can also create extended tables in the display. In an extended table, you define one row of fields and use SAS Component Language to dynamically display multiple rows based on the one you define. Refer to Extended Tables for details.

Fields

Fields in PROGRAM entries accept user input and display information or program output. You designate fields in the display with an initial ampersand (&), followed by an optional name up to eight characters in length. Use underscore characters (_) to pad the field to the length required to hold the largest field value. The field length is determined by the number of columns from the ampersand through the last underscore. A field can be as short as a single & or as long as the width of a display line.

If you omit the field name (or if you create one-character fields that consist of only an ampersand), the field is given the default name FIELDn, where n is the order of the field on the DISPLAY window, counting from left to right starting in the upper-left corner and descending.

Each field has a set of attributes that determine its appearance and behavior. Refer to PROGRAM Entry Field Attributes for information about the field attributes. When you refer to a field in the entry's SCL program, you use the name specified in the field's Alias attribute rather than the field name. By default, the field alias is the same as the field name, but you can change the alias in the entry's ATTR window to give the field a more meaningful name.

Choice Groups

You can join one or more fields into a choice group. Fields that are assigned to choice groups are referred to as stations. Only one station of a choice group can be active at a time. Pressing the ENTER key or clicking the mouse button while the cursor is on one of the fields in the choice group selects the active station. The choice group name can be used as a variable in the entry's SCL program. It returns the value of the selected station.

SAS Component Language provides functions for manipulating choice groups. Refer to SAS Component Language: Reference for more information.

Selection Lists

If you specify the List attribute for a field, users can select values for the field from a selection list. The selection list of valid field values is displayed when a user enters a designated prompt character in the first column of the field. The default prompt character is the question mark (?), but you can use the PROGRAM entry's Prompt character general attribute to specify a different prompt character for your application.

Note: If the List attribute specifies a range of values rather than a list of valid values (or if it specifies an entry that contains a list of valid values), then entering the prompt character does not display a selection list. Rather, it displays a dialog window that explains the range of valid values. [cautionend]

SAS Component Language provides a variety of functions for displaying selection lists. Refer to SAS Component Language: Reference for more information.

Extended Tables

You can use PROGRAM entries to display tables of values called extended tables. The extended table can be static, with a fixed number of rows, or dynamic, in which rows can be added or deleted. The values in the rows of the extended table can come from a SAS data set, from an array in the SCL program, or from an external file. In addition to displaying information, extended tables can be used as custom selection lists in your applications.

To create an extended table, you must

select the EXTENDED TABLE general attribute in the PROGRAM entry's GATTR window.
create the fields that define a row of the extended table in the PROGRAM entry's DISPLAY window.

Note: If you define a nonscrolling region to serve as a table heading, the fields for the extended table must appear below the ^^^ or ¬¬¬ characters that delineate the nonscrolling region.
add the SCL code to support the extended table in the PROGRAM entry's SOURCE window. Refer to SAS Component Language: Reference for more information on the SCL elements that support extended tables.

PROGRAM Entry General Attributes

PROGRAM entries also store attributes for the application window in which the entries are displayed to users. See General Attributes for Application Windows for details about the attributes you can specify for the application window.

PROGRAM Entry Field Attributes

Each field that you define in the PROGRAM entry's display has the following attributes. You specify these field attributes in the ATTR window for the PROGRAM entry. Use the ATTR command in the BUILD procedure's DISPLAY window to open the ATTR window.

Alias

specifies the name by which you refer to the field in the entry's SCL program. Each field in a PROGRAM entry must have a unique alias. By default, the alias is the same as the field name.

Choice Group

specifies a choice group to which the field belongs. The choice group name cannot be the same as an existing alias. The fields in a choice group are called stations, and the choice group variable takes the value of the active station. Only one station in a choice group can be active at a time. Refer to Choice Groups for more information on creating choice groups.

Pad

specifies the character that is used to fill blank fields in the application window. By default, fields are padded with underscore (_) characters. You can use the Pad attribute to change the pad character for an individual field. To change the default pad character for all fields, use the PADCHAR= option with the PROC BUILD statement, or issue the PDCHAR command in the DISPLAY window.

Type

specifies the type of validation that is performed to verify the values that users enter in the field. By default, fields are assigned one of the following types:

ACTION, if the field is one character in length
CHAR, if the field length is greater than one character.

Refer to Field Types for details about these and other field types that you can specify.

When a user enters a value in a field, the AF task evaluates whether the value meets the conditions of the specified type. If the value is determined to be invalid,

an error message is displayed on the application window's message line
the cursor is positioned on the field
the field is highlighted, using the color and highlighting attribute specified in the Error color and Error attr attributes.

Users cannot use the END command to exit from the application window until the field contains a valid value. They must use the CANCEL command to exit without correcting the invalid value.

Protect

controls whether field values can be changed and whether the TAB key moves the cursor to the field.

YES	specifies that users cannot change values in the field and that the TAB key does not move the cursor to the field. However, the entry's SCL program can still change the field value.
NO	specifies that users can change values in the field and that the TAB key moves the cursor to the field. This is the default behavior.
INITIAL	specifies that users cannot change values in the field, but that the TAB key moves the cursor to the field. If a user attempts to change the field value, the field reverts to the value specified in the Initial attribute when the user presses ENTER. This attribute is typically used for fields that participate in choice groups or that are assigned a push button Type attribute.

CAUTION:: If you set the Protect attribute to YES, do not select the REQUIRED option.
Making a protected field required means that users cannot use the END command to exit from the application because attempting to end the application while a required field is blank results in an error.

Format

specifies a format that controls how values that are entered in the field are displayed. You can specify any standard SAS format or a user-defined format.

Note: If you assign a format to a field, you should also assign a compatible informat. [cautionend]

Just

specifies how values that are entered in the field are aligned after the user presses ENTER.

LEFT	aligns values with the left margin of the field. This is the default behavior.
RIGHT	aligns values with the right margin of the field.
CENTER	centers values in the field width.
NONE	displays character values as they are entered. Numeric values are aligned with the right margin of the field.

Informat

specifies an informat that controls how values that are entered into the field are interpreted. You can specify any standard SAS informat or a user-defined informat.

Note: If you assign an informat to a field, you should also assign a compatible format. [cautionend]

Error color

specifies a color that is applied to the field when a user enters an invalid value. The following standard SAS color values are supported:

BLACK	CYAN	MAGENTA	RED
BLUE	GRAY	ORANGE	WHITE
BROWN	GREEN	PINK	YELLOW

Error attr

specifies a highlighting attribute that is applied to the field when a user enters an invalid value. The following attribute values are allowed, although some attributes may not be supported on some display devices: REVERSE, HIGHLIGHT, UNDERLINE, BLINKING, or NONE (the default).

Help

specifies the name and type of an entry that provides help information about the field. The specified entry is displayed when a user issues the HELP command while the cursor is positioned on the field.

Valid help entry types are CBT, HELP, MENU, and PROGRAM. Because only two-level names can be entered, the specified entry must reside in the same catalog as the current PROGRAM entry. For CBT entries, you can specify a frame number by appending the number to the entry type. For example, specify INFO and CBT5 to open the entry INFO.CBT with frame 5 displayed.

If the Help attribute is not specified for the field, the entry specified in the Help general attribute for the PROGRAM entry is displayed when a user requests help for the field.

List

determines the values that are valid for a field, provided the Type attribute permits a List attribute. Depending on the Type attribute, the List attribute can contain one or more of the following:

a list of values separated by spaces.
a range of values.

Use the less than (<) character to indicate that the List attribute value is a range. If you specify one value after the <, the range consists of all values greater than or equal to the specified value. For example, < 100 indicates all values greater than or equal to 100. If you specify a pair of values following the <, the range includes all values between and including the specified values. For example, the following range specification matches all values between 10 and 100:
```
< 10 100
```
The following range specification matches all uppercase values between A and Z:
```
< A Z
```
the name of a LIST entry that contains a list of valid values.

Use the form =libref.catalog-name.entry-name to specify the name of the LIST entry. Note that an equal sign (=) is added as a prefix. You can omit the libref.catalog-name portion if the LIST entry is in the same catalog as the current PROGRAM entry. Refer to LIST Entries for more information about LIST entries.
the name of a data set or the name of one or more fields that contain the names of SAS data sets.

For types such as ONEVAR, VARLIST, and VARSTMT that verify the names of variables in a data set, the value of the List attribute determines which data set is searched for the variables that are specified in the field.

Use the form *libref.data-set-name to specify the data set name. Note that an asterisk (*) is added as a prefix.

If you specify one or more field names that contain data set names, the corresponding fields should be defined as INPUT type to ensure that the data sets named in the fields exist. By default, the field values are valid only if specified variables exist in all the data sets named in the variable. To specify that the field values are valid if the specified variables exist in one or more of the data sets, add an at (@) character as the first character in the List attribute value.

You can also use the List attribute to specify a selection list for the field. In this case, the List attribute has the following form:

\<prompt> <num-sel> =entry-name<C | F | L> | @link-name\

where

prompt

specifies the prompt character that displays the selection list when a user enters it as the first character in the field. If you omit the prompt argument, the default is the question mark (?).

num-sel

specifies how many items users can select from the list. If you omit the num-sel argument, the default is 1.

=entry-name <C | F | L>

specifies a LIST, HELP, or CBT entry that provides the items for the selection list.

If you specify a HELP entry, each line of text in the entry's display becomes an item in the selection list. You can add one of the following options to specify which portion of the selected line is returned:

C	indicates that the word at the cursor position in the selected line is returned. This option is valid only when one selection is allowed.
F	indicates that the first word on the selected line is returned. This is the default behavior.
L	indicates that the entire selected line is returned.

@link-name

specifies the name of a linked field that determines which type of format or informat information is displayed. This form of the List attribute is valid only for fields of type FMT or INFMT. If the first character in the linked field is C or $, then Help on character formats or informats is displayed. Otherwise, Help on numeric formats or informats is displayed. Only the names of formats or informats of the corresponding type can be entered in the field.

Initial

specifies a character string (up to 56 characters) or a numeric value that is displayed in the field when the PROGRAM entry is initially displayed to a user in the application window. If the Initial attribute is blank, the field is represented with the specified pad character or with a default pad character.

Replace

specifies a character string (up to 56 characters) that is used as a replacement string when values are substituted in SUBMIT blocks in the PROGRAM entry's SCL program. Refer to the description of the REPLACE statement in SAS Component Language: Reference for more information about replacement strings.

Options

control the following characteristics of the field:

CAPS	specifies that characters entered into the field are converted to uppercase when the user presses ENTER. This attribute is selected by default. Deselect this attribute if you want users to be able to enter mixed-case values in the field.
CURSOR	specifies that the cursor is positioned on the field when the application window opens. By default, the CURSOR attribute is selected for the first field created in the DISPLAY window and is deselected for the remaining fields. Only one field should have the CURSOR attribute selected. If more than one field has the CURSOR attribute selected, the cursor is initially positioned on the first field that has the attribute selected.
REQUIRED	specifies that a user must enter a valid value in the field before the application window can be closed with the END command. CAUTION: If you select the REQUIRED option, do not set the Protect attribute to YES. Protecting a required field means that users cannot use the END command to exit from the application because attempting to end the application while a required field is blank results in an error.
AUTOSKIP	specifies that the cursor moves automatically to the next unprotected field when user input fills the current field's last position. By default, the AUTOSKIP attribute is selected for all fields. Deselect the AUTOSKIP attribute if you want the cursor to remain on the current field when a user enters values that fill the field.
NOPROMPT	specifies that the prompt character is ignored for the field. By default, when a user enters a designated prompt character in the first position of the field, the AF task displays either a selection list of valid values or information about the range of valid values for the field. (The behavior depends on the value of the List attribute.) Select the NOPROMPT option to disable this behavior and treat the prompt character like a regular text character. The prompt character for the entry is specified in the entry's Prompt character general attribute. The default prompt character is the question mark (?).
NON-DISPLAY	specifies that values that users enter in the field are not displayed in the application window. Users can still tab to a nondisplayed field (provided the field is not protected), and field values are still validated. This attribute is useful when the field is used for entering passwords or other values that should be kept hidden.

Field Types

The Type field in PROGRAM entries can take one of the following attribute values:

ACTION

specifies that the value that a user enters in the field is converted to a predefined character or character string. For ACTION fields for which no List attribute is specified, a value entered in the field is automatically converted to uppercase X. If a List attribute is specified, then any value entered in the field is automatically converted to the value that is specified as the field's List attribute. This enables you to define the value for the field as a single character (for example, *) or as a word (for example, YES).

ATTR

verifies that the field value is the name of a text highlighting attribute. Valid values are REVERSE, HIGHLIGHT, UNDERLINE, BLINKING, or NONE, or the corresponding one-character abbreviations (R, H, U, B, or N).

CHAR

verifies that the field value is standard SAS character data.

CHARLST

verifies that the field contains a list of standard SAS character data values. Values in the list are separated by spaces.

COLOR

verifies that the field value is one of the standard SAS color names:

BLACK	CYAN	MAGENTA	RED
BLUE	GRAY	ORANGE	WHITE
BROWN	GREEN	PINK	YELLOW

DSNAME

verifies that the field value is a valid one- or two-level SAS data set name.

Note: The DSNAME type tests only whether the specified name is valid, not whether the specified data set exists. Use the INPUT type to verify that the specified data set exists, or use the OUTPUT type to verify that the specified data set does not exist. [cautionend]

FILENAME

verifies that the field value is a fileref that has been previously defined in the current SAS session.

FIXED

verifies that the field value is an integer numeric value.

FIXEDLST

verifies that the field contains a list of integer numeric values. Values in the list are separated by spaces.

FMT FMTC FMTN

verify that the field value is a valid format name. Use FMTC to verify that the field value is the name of a character format, or use FMTN to verify that it is the name of a numeric format. Use FMT to verify that the field value is the name of either a character format or a numeric format.

Note: Do not specify a value for the List attribute when you specify FMT, FMTC, or FMTN for the Type attribute. The field value is validated against the list of all standard SAS formats and user-defined formats. [cautionend]

INFMT INFMTC INFMTN

verify that the field value is a valid informat name. Use INFMTC to verify that the field value is the name of a character informat, or use INFMTN to verify that it is the name of a numeric informat. Use INFMT to verify that the field value is the name of either a character informat or a numeric informat.

Note: Do not specify a value for the List attribute when you specify INFMT, INFMTC, or INFMTN for the Type attribute. The field value is validated against the list of all standard SAS informats and user-defined informats. [cautionend]

INPUT

verifies that the field value is the name of an existing SAS data set.

INPUTALL

verifies that the field value is either a list of names of existing SAS data sets or the special SAS designation _ALL_.

Note: The default pad character for this type of field should be a character other than the default underscore. It should also be a character that is not likely to be used in a data set name. [cautionend]

LIBNAME

verifies that the field value is a libref that has previously been defined in the current SAS session.

NAME

verifies that the field value is a valid SAS name.

NUM

verifies that the field value is a standard SAS numeric value.

Note: Use the FIXED type if you want to restrict the field to integer values. [cautionend]

NUMLST

verifies that the field contains a list of standard SAS numeric values. Values in the list are separated by spaces.

Note: Use the FIXEDLST type if you want to restrict the field to a list of integer values. [cautionend]

ONEVAR ONEVARC ONEVARN

verify that the field value is the name of one variable from a SAS data set. Use ONEVARC to verify that the field value is the name of a character variable, or use ONEVARN to verify that it is the name of a numeric variable. Use ONEVAR to verify that the field name is the name of either a character variable or a numeric variable.

The List attribute specifies which data set to search for the variable. The List attribute can specify either the name of the data set or the names of fields that contain the name of the data set. If the List attribute is not specified, the PROGRAM entry's Lookup data set general attribute is used. The Lookup data set general attribute contains the name of a field that contains the name of the data set to search.

OUTPUT

verifies that the field value is a valid data set name and that the specified data set does not currently exist.

Note: The OUTPUT field type is typically used for names of data sets that are created for application output. This type of validation ensures that the output data set does not overwrite an existing data set. [cautionend]

PUSHBTNC PUSHBTNN

display the field as a push button that users can click (or move the cursor to and press ENTER) to cause an action to occur. Use the Initial attribute to specify the value that appears as the button label. Use PUSHBTNC for fields that return character values, or use PUSHBTNN for fields that return numeric values.

SHORT

verifies that the field value is an integer number in the range of -32767 to 32767.

VARLIST VARLISTC VARLISTN

verify that the field contains a list of variable names that appear in a data set. Use VARLISTC to verify that the field contains the names of character variables, or use VARLISTN to verify that it contains the names of numeric variables. Use VARLIST to verify that the field contains the names of either character variables or numeric variables. These types ignore any other characters in the field, such as arithmetic operators, and verify only the field's variable names.

VARSTMT VARSTMTC VARSTMTN

verify that the field contains a list of variable names that appear in a data set. Use VARSTMTC to verify that the field contains the names of character variables, or use VARSTMTN to verify that it contains the names of numeric variables. Use VARSTMT to verify that the field contains the names of either character or numeric variables. These types allows only variable names to be entered into the field. Use VARLIST (or VARLISTC or VARLISTN) to allow the field to contain other characters in addition to the variable names.

The List attribute specifies the data set to search for the variable. The List attribute can specify either the name of the data set or the names of fields that contain the name of the data set. If the List attribute is not specified, the PROGRAM entry's Lookup data set general attribute is used. The Lookup data set general attribute contains the name of a field that contains the name of the data set to search.

PROGRAM Entry SCL Programs

PROGRAM entries can store a SAS Component Language (SCL) program that can manipulate field values and control the behavior of the entry. You use the BUILD procedure's SOURCE window to edit the PROGRAM entry's SCL program. You can issue the SOURCE command in the DISPLAY window to open the SOURCE window for the entry. Refer to SAS Component Language: Reference for details about the statements and functions that you can use in SCL programs.

Before the SCL code in an PROGRAM entry can be executed, it must be compiled. To compile the program, issue the COMPILE command in either the SOURCE window or the DISPLAY window for the entry. You can also use the COMPILE statement with the PROC BUILD statement to compile the contents of existing PROGRAM entries.

When the source code in the SCL entry is compiled, the SCL compiler writes any error or warning messages to the SAS log. If the SCL program is compiled successfully, the compiled code is added to the PROGRAM entry along with the source code.

When you invoke a PROGRAM entry, the AF task executes the statements in the program's INIT section. When you modify a field value, statements in the program's MAIN section are executed. If the program contains labeled sections whose labels match the names of the modified fields, then those sections are also executed before the MAIN section. Statements in the TERM section of the program are executed when you end the PROGRAM entry. Refer to SAS Component Language: Reference for more information on SAS Component Language processing.

Top of Page