SAS/AF Catalog Entry Types

CBT Entries

CBT entries store interactive user assistance or tutorial applications, which consist of

a display that provides information and questions to users and which accepts user responses
general attributes that control the appearance and behavior of the window in which the CBT entry executes
a Child attribute that specifies another entry to which control can be passed when users reach the last frame in the CBT entry.

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

You use the BUILD procedure's DISPLAY window to design the displays for CBT 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 or select answers to questions, as well as graphics.

The display for a CBT entry is divided into a sequence of frames. Frame boundaries in the display are indicated with either a frame indicator line or a divider line that consists of dash (-) characters across the full width of the DISPLAY window. (You can use the FILL command in the DISPLAY window to create divider lines.) Refer to Frame Indicator Syntax for information about the syntax of frame indicator lines.

In addition to presenting information to users, frames in CBT entries can pose both fill-in-the-blank and multiple-choice questions. Refer to Query Frames for details about creating frames that present questions. If the frame contains a question for users, it must begin with a frame indicator line, and it must include one or more feedback indicator lines that determine how the entry responds to user input. Refer to Feedback Indicator Syntax for information about the syntax of feedback indicator lines.

If a frame does not present a question, users can press ENTER to advance to the next frame in the sequence. If the frame presents a question, users must either attempt to answer the question or use the FORWARD command to skip the question. Users can issue the BACKWARD command to scroll back to previous frames in the sequence. When a user issues an END command to close the CBT entry, the current entry name is stored as the AF checkpoint (unless the CHECKLAST=NO option was specified in the AF command that started the application). Users can issue the SAVE command to save the current frame number and end the current SAS session. When the user opens the CBT entry again, it resumes at the frame that was displayed when the SAVE command was issued.

You can define frames that branch unconditionally to other SAS/AF catalog entries. To define a frame that jumps to another entry, use a divider line to begin the frame, and enter three uppercase P characters in the first three columns of the next line. Follow the PPP with the name of the entry to open.

Scrolling Controls

If you design a frame that has more lines than the current window size, only the number of lines that fit in the window are initially displayed. Users must issue a FORWARD command to display the remaining lines of the frame. You can designate a portion of the frame that does not scroll. Enter three caret (^) or NOT (¬) characters in the first three columns of a line to delineate the nonscrolling region of the frame. Any text and fields above the line that contains the ^^^ or ¬¬¬ remain visible as long as the current frame is displayed; FORWARD and BACKWARD commands scroll only the region below the nonscrolling area.

You can define pause indicators in the display to delay the presentation of portions of the text. Enter three at (@) characters in the first three columns of a line to define a pause. Only the text between the beginning of the frame and the first pause indicator (@@@) appears when the frame is initially displayed. When the user presses ENTER, the text from the current pause indicator up to the next pause indicator (or up to the end of the frame, if there are no more pause indicators) is added to the frame, and so on.

You can use the LOCK option in the frame indicator to segment frames. A frame indicator line with the LOCK option ends a sequence of frames. Users cannot press the ENTER key or issue FORWARD or BACKWARD commands to move into or out of a locked frame. Locked frames are displayed only when they are specifically called, such as in a branch from a feedback item in another frame.

Query Frames

CBT entries can pose either fill-in-the-blank or multiple-choice questions. If a frame poses a question, the user cannot press the ENTER key to move to the next frame without attempting to answer the question. However, the FORWARD command can be used to skip the question, unless the field is locked.

You designate the response field for a fill-in-the-blank question with an initial ampersand (&), followed by underscore (_) characters to pad the field to the length required to hold the largest answer value. A response field can be as short as a single & or as long as the width of a display line. The ampersand and pad characters do not appear when the frame is displayed to the user.

Use the CORRECT= option in the frame indicator to specify the correct answer to the fill-in-the-blank question. You can use feedback indicators to define the entry's response to correct or incorrect answers. The feedback indicators can either display messages or branch to other frames or entries.

Designate the response fields for multiple-choice questions with underscore (_) characters. The underscore for each response field should be preceded and followed by a space. You can use up to eight multiple-choice response fields in a frame. When the frame is displayed to users, they can use the TAB key to move the cursor from field to field, and they can either press ENTER or click the mouse to select the desired field.

Each multiple-choice response field should have a corresponding feedback indicator that specifies the entry's response to the selection. The feedback indicators can either display messages or branch to other frames or entries. Use the C option in the feedback indicator to indicate which responses are considered correct.

You can collect information about the user's responses to the questions in the CBT entry. The response statistics are stored in a SAS data set. Refer to the descriptions of the QUIZ= and QUIZ options in Frame Indicator Options for details.

The AF task creates the following macro variables when a CBT entry is executed:

&_NQSEEN, which stores the number of questions presented to the user
&_NQRIGHT, which stores the number of questions that the user answered correctly.

You can use these macro variables in other SAS programs after the CBT entry ends.

In addition to response fields, you can define the following other methods for enabling users to interact with the frames in a CBT entry:

You can use the SELECT= option in feedback indicator lines to create selection boxes, which are areas of the display in which users can either press ENTER or click the mouse to select the corresponding feedback item.
You can use the MENU= option in feedback indicator lines to define values that users can enter on the application window's command line to select the corresponding feedback item.

The feedback items for selection boxes and menu choices can either display a message or branch to a specified frame or entry.

Frame Indicator Syntax

The general form of a frame indicator is

? <* | n> <options>

where options can be one or more of the following:

AUTO | AUTO=n | NOAUTO

CORRECT=answer-value | `answer-string' | ?

GRAPH=<(left-col, right-col, top-row, bottom-row)> libref.catalog-name.graphic-entry </ERASE>

LOCK

NAME=frame-name

QUIZ

QUIZ=<libref.>response-data-set

SOUND | MUSIC=freq-1 duration-1 <... freq-n duration-n> | note-1 duration-1 <... note-n duration-n>

WRONG=<libref.catalog-name.>entry-name.entry-type

Use the slash character (/) to continue a frame indicator across multiple lines of the display. For example, the following lines comprise a single frame indicator:

?2 name=mean /
   correct=42 /
   wrong=review.cbt

Frame Indicator Options

You can use the following options in frame indicators:

*

indicates that the remainder of the line is a comment.

n

specifies how many attempts the user is given to provide the correct answer to the question in the frame. The value for n must be in the range 1 to 8, and it must appear in column 2 of the feedback indicator line.

If you omit the n option, feedback indicator lines in the frame are ignored, so the value of n should always be at least 1 if the frame includes feedback indicator lines.

If the user fails to enter or select the correct answer to the question within the allotted number of attempts, then by default the correct answer is displayed, and the user is prompted to press ENTER to continue. However, if the frame indicator includes the WRONG= option, then control passes to the specified entry.

AUTO AUTO=n NOAUTO

specify the beginning or end of a sequence of frames that are displayed without waiting for user input. Use the AUTO option to display frames as fast as the display device allows. Use AUTO=n to specify the rate at which frames are displayed, where n is the number of frames per second to display.

By default, frames from the current sequence are displayed until a query frame is encountered or until the last frame of the sequence is displayed. Use the NOAUTO option to stop the automatic display before the last frame is reached.

CORRECT=answer-value | `answer-string' | ?

specifies the correct answer when the frame includes a fill-in-the-blank question. The answer can be up to 32 characters long. Enclose the answer string in single or double quotes if it contains embedded blanks.

If you specify CORRECT=?, then any answer that a user enters in the response field is considered correct.

GRAPH=<(left-col, right-col, top-row, bottom-row)> libref.catalog-name.graph-entry </ERASE>

specifies a graph to be displayed in the frame. The graph must be a catalog entry of type GRSEG created with SAS/GRAPH software. You must specify the libref.catalog-name portion of the entry name, even if the entry resides in the same catalog as the CBT entry.

Note: In order for users to see the graph when the CBT entry runs in the application window, SAS/GRAPH software must be licensed at their site, and their display devices must support SAS/GRAPH output. [cautionend]

By default, the graph is displayed starting on the second row of the display area to leave room for a line of text above. The display must contain enough blank lines so that the graph does not overlay any text. You can specify left and right column values and top and bottom row values to control the position of the graph within the display. The position values must be enclosed in parentheses. The following rules apply:

the left-col value must be greater than 1 and less than the number of columns in the display. (Column 1 is reserved for frame and feedback indicators.)
the right-col value must be greater than 2 and less than the number of columns in the display.
the top-row value can be 1 or greater, but it must be less than the number of rows in the display minus 2.
the bottom-row value must be greater than 1 and equal to or less than the number of rows in the display minus 2.

By default, any new graph that you display overlays any previous graph. Add the /ERASE option to erase any previous graphs before displaying the current graph. To erase the previous graph without displaying a new graph, specify the following:

graph=erase.erase.erase/erase

LOCK

specifies a frame that is not part of a sequence. Users cannot use the ENTER key or the FORWARD and BACKWARD commands to scroll into or out of locked frames. Locked frames are displayed only when they are explicitly called, such as when they are the target of a branch in a feedback indicator. To exit from a locked frame, a user must either answer a question that branches to a different frame or issue an END command. The END command returns to the CBT frame that called the locked frame.

NAME=frame-name

specifies a name for the frame that can be used instead of the frame number when another frame branches to the frame. Using frame names for branch targets is preferable to using frame numbers because a frame's number can change as frames are added or removed.

QUIZ

specifies that information about the user's responses to the question in the current frame is recorded in the SAS data set specified in the QUIZ= option.

QUIZ=<libref.>response-data-set

specifies the name of a SAS data set that is used to record information about the user's responses to questions in the frames of the CBT entry. If you omit the libref portion of the data set name, the data set is created in the default WORK library.

Note: Use the QUIZ= option in the first frame for which you wish to collect response data, and use the QUIZ option in subsequent frames. [cautionend]

The tracking data set contains the following variables:

LIBREF

is the libref that contains the catalog where the CBT entry resides.

CATNAME

is the name of the catalog that contains the CBT entry.

OBJNAME

is the name of the CBT entry (or XTESTAFX, if you are testing the entry with the TESTAF command).

FRAME

is the frame number for which response data was recorded.

MATRICES

is the number of attempts that the user is allotted to answer the question.

TRIES

is the number of attempts that the user actually used.

Note: The number of attempts is not incremented if the frame does not specify a correct answer for the question. [cautionend]

SCORE

is a number that represents the user's success in answering the question in the frame, as follows:

-1	indicates that the user exhausted all allotted attempts and failed to answer the question correctly.
0	indicates that the user answered the question incorrectly and did not use all the allotted attempts before requesting the correct response.
1	indicates that the user gave the correct response.
2	indicates that the user skipped the frame.

SOUND=freq-1 duration-1 <... freq-n duration-n> | note-1 duration-1 <... note-n duration-n> MUSIC=freq-1 duration-1 <... freq-n duration-n> | note-1 duration-1 <... note-n duration-n>

specifies one or more tones or notes that are played when the frame is displayed, provided the user's display device supports sounds.

You can use either of the following formats to specify the sounds to play:

frequency-duration pairs, where freq is the frequency of the tone in cycles per second and duration is the duration of the tone in units of 1/100ths of a second.
note-duration pairs, where note is a note specification and duration is the duration of the note in units of 1/100ths of a second. A note specification consists of the note name from the musical scale (A, B, C, D, E, F, or G) and an octave designation (0-7, corresponding to the octaves on a piano keyboard, starting at the bass end). You can also add a # to raise the note by a half tone or a lowercase b to lower the note by a half tone. For example, E6b specifies an E flat in octave 6.

For a rest (silence), specify either 0 for the frequency or Z for the note name.

Note: Users can use the SOUND command in the application window to turn sounds on or off. [cautionend]

WRONG=<libref.catalog-name.>entry-name.entry-type

specifies an entry that is displayed when the user fails to give the correct response in the allotted number of attempts.

Feedback Indicator Syntax

The general form of a feedback indicator is

#<n<C>> <branch> <options>

where options can be one or more of the following:

FRAME=frame-number | frame-name

HELP=<libref.catalog-name.>entry-name.entry-type

MENU=value

SELECT=(left-col, right-col, top-row, bottom-row)

SOUND | MUSIC=freq-1 duration-1 <... freq-n duration-n> | note-1 duration-1 <... note-n duration-n>

Use the slash character (/) to continue a feedback indicator across multiple lines of the display. For example, the following lines comprise a single feedback indicator:

#1 >< fruit.cbt frame=app /
   select=(10,14,3,3) /
   menu=apple

If you do not use the branch option in the feedback indicator, you can follow the feedback indicator with one or more lines of text. The lines of text that follow the feedback indicator are displayed when users select the corresponding response field or selection box. If the indicator designates a correct response, the first line of text after the indicator is considered the congratulatory message, and the remaining lines are considered the explanatory message. Both are displayed when a user enters a correct response, but only the explanatory lines are displayed if the user fails to give the correct response in the allotted number of attempts or when the user asks to see the correct response without giving the correct response.

Feedback Indicator Options

You can use the following options in feedback indicators:

n

specifies the sequence number of the feedback item. This value must appear in column 2 of the feedback indicator line.

If the frame includes a fill-in-the-blank question, then use the value 1 to provide feedback on user responses to the question. If the frame includes a multiple-choice question, the value of n should correspond to the order of the choice field (1 for the first choice, 2 for the second choice, and so on). For feedback indicators that are not associated with response fields (for example, when the SELECT= or MENU= options are used), the value of n is not significant.

C

designates a correct response. For multiple-choice questions, you can designate more than one correct response.

branch

specifies that the corresponding feedback response branches to another entry rather than displaying feedback text. Use one of the following forms for the branch specification:

> <libref.catalog-name.>entry-name.entry-type: branches to the specified entry and stores the current frame number as the CBT checkpoint. The current frame is displayed the next time the CBT entry is opened.
>> <libref.catalog-name.>entry-name.entry-type: branches to the specified entry but does not store a CBT checkpoint. The first frame is displayed the next time the CBT entry is opened.
>< <libref.catalog-name.>entry-name.entry-type: branches to the specified entry and returns to the branching frame when the target entry is closed.

FRAME=frame-number | frame-name

specifies the frame number or frame name to display when the target of the branch option or the entry specified in the HELP= option is a CBT entry.

HELP=<libref.catalog-name.>entry-name.entry-type

specifies an entry to open when a user issues the HELP command while the cursor is positioned on the corresponding response field or selection box.

Note: If you do not specify the HELP= option, the HELP command opens the entry specified in the Help general attribute for the CBT entry. [cautionend]

MENU=value

specifies a value that users can enter on the application window's command line to select the corresponding feedback response.

SELECT=(left-col, right-col, top-row, bottom-row)

specifies the coordinates of a rectangular region that comprises the selection box for the feedback item. The selection box is highlighted when a user moves the cursor into that region of the display, If a user presses the ENTER key or clicks the mouse while the cursor is within the selection box, the corresponding feedback item is selected. Users can press the TAB key to move between the selection boxes in the current frame.

Selection boxes should be separated by at least one space.

SOUND=freq-1 duration-1 <... freq-n duration-n> | note-1 duration-1 <... note-n duration-n> MUSIC=freq-1 duration-1 <... freq-n duration-n> | note-1 duration-1 <... note-n duration-n>

specifies tones or notes that play when the feedback item is selected, provided the user's display device supports sound. Refer to the description of the SOUND= option for frame indicators in Frame Indicator Options for details about the argument values.

CBT Entry General Attributes

CBT 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 general attributes you can specify for the application window.

CBT Entry Child Attribute

CBT entries can store a Child attribute that specifies the name of another SAS/AF entry that opens if users press ENTER from the last frame of the CBT entry. You specify the Child attribute in the ATTR window for the CBT entry. Use the ATTR command in the BUILD procedure's DISPLAY window to open the ATTR window.

Note: The child entry is opened only when a user presses the ENTER key while the final frame of the CBT entry is displayed. Use the Parent general attribute to specify an entry to open when users end some other CBT entry. [cautionend]

The Child attribute consists of the four-level name of the entry to open. If the target entry is in the same catalog as the CBT entry, you only need to specify the name and type of the target entry. If the target entry is stored in a different catalog or in a catalog in a different library, then you must also specify the libref and catalog for the target entry.

Top of Page