SAS Component Language Dictionary

DISPLAY

Runs a catalog entry that was created with SAS/AF software

Category:

Modular Programming and Object Oriented

Syntax
Details
Examples
	Example 1: Passing Parameters
	Example 2: Passing Array Parameters by Reference
See Also

Syntax

CALL DISPLAY(entry<,parameters>);

return-value=DISPLAY(entry<,parameters>);

entry

is a display entry (FRAME, PROGRAM, SCL, MENU, HELP, or CBT) that was created using SAS/AF software. It is specified as

entry-name: for a PROGRAM entry in the current catalog.
entry.type: for an entry of the specified type in the current catalog.
libref.catalog.entry: for a PROGRAM entry in the specified catalog.
libref.catalog.entry.type: for an entry of a specified type in a specified catalog.

Type: Character

parameters

lists one or more parameters to pass to the called entry. You can pass parameters to FRAME, PROGRAM, and SCL entries. In order for the called entry to accept these parameters, it must contain a corresponding ENTRY statement.

Note: These parameters are update parameters. See Input, Output, and Update Parameters for more information. [cautionend]

Type: Numeric, Character

return-value

contains the value that is returned by the called entry. The data type for return-value should match the data type for the called entry.

Type: Numeric, Character, List, Object, Class, or Interface

Details

DISPLAY can run a FRAME, PROGRAM, SCL, MENU, HELP, or CBT entry and make it the active entry. When the called entry is exited, control returns to the calling program.

DISPLAY can pass parameters to a FRAME, PROGRAM, or SCL entry and receive a return value. Parameters can be numeric constants, character constants, variables, expressions, and array variables. Parameters are passed to the ENTRY statement in the called entry.

Using DISPLAY without any options in the associated ENTRY statement requires a strict correspondence between DISPLAY parameters and ENTRY statement arguments. The arguments and parameters must agree in number, data type, and relative position. If you pass an incorrect number of parameters or a parameter of the incorrect type, SCL halts the execution of the program. The argument-parameter correspondence is less restrictive when you use the options REST=, ARGLIST=, and OPTIONAL= in the ENTRY statement. See ENTRY for examples of these options.

Names listed in parameter do not have to match the argument names in the ENTRY statement.

Parameters are passed in the following ways:

call-by-reference

enables the specified entry to change the values of the parameters. If you do not want the values of the parameters to be modified, use the NOCHANGE routine. Or, if you do not want to return the new values for specific parameters, use the INPUT option for that parameter in the ENTRY statement. Here is an example of call-by-reference:

array employee{50};
call display('b.frame',var1,name,num,employee{1});

call-by-value

prevents the specified entry from changing the values of the parameters. Call-by-value is used for all numeric constants, character constants, and expressions. Here is an example of call-by-value:

call display('b.frame',100,'hello',x+y);

Note: Use CALL CBT to run CBT applications, because it provides more options used by CBT entries. In general, you may want to use CALL GOTO instead of CALL DISPLAY if you do not need control to return to the calling program. This may be helpful for applications that have memory constraints. [cautionend]

Examples

Example 1: Passing Parameters

Use DISPLAY in program X to pass parameters to program Y. Program Y then declares these arguments with an ENTRY statement. Variables I and S are call-by-reference parameters, and the constant 1 is a call-by-value parameter.

X.SCL contains the following program:

INIT:
   s = 'abcd';
   i = 2;
   call display('y.frame', i, 1, s);
      /* At this point, after the return from Y, */
      /* i=7 and s='abcde'                       */
   put i= s=;
return;
MAIN:
TERM:
return;

Y.SCL contains the following program:

entry j c:num str:char;
init:
   j = length(str) + c;
   j = j + 2;
   str = str || 'e';
   c = 2;
return;

The following correspondence occurs:

The value of variable I passes to variable J.
The literal value 1 passes to variable C.
The value of variable S passes to variable STR.

After program Y runs, the values of variables J and STR are returned to the variables I and S, respectively. The variable C cannot return a value, however, because the corresponding parameter in DISPLAY is a constant.

Example 2: Passing Array Parameters by Reference

Use DISPLAY to pass array parameters by reference. In this example, the variables S and A are call-by-reference parameters, and the constant 4 is a call-by-value parameter.

X.SCL contains the following program:

array a{4} 8;
INIT:
   a{1} = 1; a{2} = 2; a{3} = 3; a{4} = 4;
   s = 0;
   call display('y.frame', s, a, 4);
     /*  At this point, after the return
                                 from Y, */
     /*  s=10, a{1}=2, a{2}=4, a{3}=6,
                               a{4}=8.   */
   put s= a=;
return;

MAIN:
TERM:
return;

Y.SCL contains the following program:

array arr{*} 8;
entry sum arr[*] len:num;
INIT:
   do i = 1 to len;
      sum = sum + arr{i};
      arr{i} = 2 * arr{i};
   end;
return;

The following correspondence occurs:

The value of variable S passes to variable SUM.
The array variable A is passed to the array variable ARR.
The literal value 4 passes to variable LEN.

After program Y runs, the value of the variable SUM is returned to the variable S, and the values in the array ARR are returned to the corresponding values in the array A. The variable LEN cannot return a value, however, because the corresponding parameter in DISPLAY is a constant.