Control statements

This topic describes each of the ISPF file tailoring control statements:

)BLANK

The specified number of blank lines are placed in the output file at the point where the )BLANK statement is encountered. The number parameter can be specified as a symbolic variable. If number is omitted, the default value is 1.

Example:

)BLANK

)BLANK &SPACER

The first example inserts one blank line into the output file. In the second example, the number of blank lines inserted is equal to the current value of the variable SPACER.

)CM

The statement is treated as a comment. No tailoring is performed, and the record is not placed in the output file. Comment statements cannot be continued.

In addition, comment control statements are ignored in these cases:

When specified as the control statement for either the )IF or )ELSE control statements.
When embedded within another control statement that includes continuation across two or more input records

)DEFAULT

The seven characters represented by abcdefg override the use of the ), &, ?, !, <, |, and > characters, respectively. Exactly seven characters must be specified.

If you are using a non-U.S. keyboard, refer to Character translations for APL, TEXT, and Katakana for text keyboard character translations.

The )DEFAULT statement takes effect immediately when it is encountered. It remains in effect until the end of FTINCL processing, or until another )DEFAULT statement is encountered. If the )DEFAULT statement is used to change defaults during an imbed, it is only in effect for that imbed level. It does not apply to deeper or previous imbed levels. The defaults will not be in effect for any imbedded skeletons but will be in effect for any data in the skeleton after the )IM. The )DEFAULT statement cannot be continued.

Example 1:

This example demonstrates that defaults changed using )DEFAULT do not take effect in imbedded skeletons.

This skeleton changes the variable name control character & to the ø sign:

   )DEFAULT )ø?!<|>
   )SET A = USERNAME
   A: øA
   )IM SKEL2
   A: øA

An FTINCL of this skeleton imbeds SKEL2, which contains:

   AA: øA
   AA: &A

This results in this data in the output data set:

   A: USERNAME
   AA: øA
   AA: USERNAME
   A: USERNAME

Example 2:

This example demonstrates that defaults changed in an imbedded skeleton are not passed back to the skeleton doing the )IMBED.

An FTINCL of this skeleton imbeds SKEL3:

   )SET A = USERNAME
   A: øA
   )IM SKEL3
   A: øA

SKEL3 changes the variable name control character & to the ø sign:

   )DEFAULT )ø?!<|>
   AA: øA
   AA: &A

This results in this data in the output data set:

   A: øA
   AA: USERNAME
   AA: &A
   A: øA

Example 3:

This example demonstrates how to use the NT parameter to prevent tailoring from occurring when imbedding a file. Using NT eliminates having to change defaults in the imbedded skeleton when it contains default control characters.

An FTINCL of this skeleton imbeds a skeleton with the NT parameter:

     )SET A = LBL1
     &A:
     )IM SKEL4 NT
       GO TO &A

The imbedded skeleton SKEL4 contains:

     IF (&A < 0) | (&A > 10) THEN
       &A = 0
     ELSE

This results in this data in the output data set:

     LBL1:
     IF (&A < 0) | (&A > 10) THEN
       &A = 0
     ELSE
       GO TO LBL1

)DO )ENDDO

The skeleton input records between the )DO and the corresponding )ENDDO statements are repeatedly processed until a condition causes the )DO loop to terminate. Processing then continues with the input record immediately following the )ENDDO statement.

The processing of a )DO loop can be prematurely ended using the )LEAVE statement, or the current iteration of the )DO loop can be terminated using the )ITERATE statement.

There are several different formats of the )DO statement supported by file tailoring. The possible syntaxes are:

var: The control variable name.
n: The starting value, which can be either a positive or a negative integer in the range -2147483648 to 2147483647.
m: The ending value, which can be either a positive or a negative integer in the range -2147483648 to 2147483647.
incr: The increment value, which can be either a positive or a negative integer in the range -2147483648 to 2147483647. Default value is 1.
cnt: The maximum number of iterations of the )DO loop to be performed. The number can be either a positive or a negative integer in the range -2147483648 to 2147483647. If cnt is less than 1, the )DO statement is skipped.

until_expression is a relational expression that is evaluated for a true or false condition. The )DO loop continues while the until_expression evaluates to a false condition. The test is performed at the end of each loop prior to updating the control variable. The loop is always performed at least once.

while_expression is a relational expression that is evaluated for a true or false condition. The )DO loop continues while the while_expression evaluates to a true condition. The test is performed at the start of each loop, once the control variables are initialized.

count is an integer number used to control the number of iterations of the )DO loop. The number can be either a positive or a negative integer in the range -2147483648 to 2147483647. If the count is less than 1, the )DO statement is skipped. The default value for count is 1.

FOREVER continues processing the )DO loop until a )LEAVE statement within the loop terminates the )DO loop. All other parameters are ignored when using the FOREVER parameter. File tailoring makes no attempt to determine if a )DO FOREVER loop can be suitably terminated.

Example 1

This example performs a loop 10 times with the control variable, I, starting at 1 and increasing by 1 each time. The control variable will have the value 11 at the end of the loop.

)DO I = 1 TO 10
. . .
)ENDDO

Example 2

This example shows a )DO loop that is to continue until the variable RC is nonzero.

)SET RC = 0
)DO FOREVER
. . .
)IF &RC ¬= 0 THEN )LEAVE
. . .
)ENDDO

Example 3

This is another example of a )DO loop that is to continue until the variable RC is nonzero. Note that testing of the variable RC is performed at the start of each loop.

)SET RC = 0
)DO WHILE &RC = 0
. . .
)ENDDO

Example 4

This example performs a loop 10 times. There is no control variable.

)DO 10
. . .
)ENDDO

)DOT )ENDDOT

Note: The )DOT command parameter table-name must be in uppercase for use with ISPF table services.

The skeleton input records between the )DOT and the corresponding )ENDDOT are iteratively processed as follows:

Where the SCAN keyword is not provided, the skeleton input records are processed for each row of the table, beginning with the first row.
Where the SCAN keyword is provided, the skeleton input records are processed for only those rows of the table that match the current scan arguments.
- Where the additional name-cond-pairs parameter is not specified, a search argument must have already been established for the ISPF table, table-name. This requires table-name to have been opened and a valid search argument established using the TBSARG service before the file tailoring services are invoked. A severe dialog error will occur if the SCAN keyword is specified and valid search arguments have not yet been established for the table.
- Where the additional name-cond-pairs parameter is specified, file tailoring services will use the variable names and condition values to process the table. The dialog variables must already be initialized to the required values for the TBSCAN service. The syntax of the name-cond-pairs is exactly the same as for the TBSARG name-cond-pairs parameter.
Where the OPT keyword is not provided, if the table does not exist the file tailoring is terminated with an error message.
Where the OPT keyword is provided, if the table does not exist the file tailoring processing is the same as for an empty table.
Where both the SCAN and OPT keywords are provided, the SCAN keyword must immediately follow the table-name.

At the start of each iteration, the contents of the current table row are stored into the corresponding dialog variables. Those values can then be used as parameters in control statements or substituted into data records. Up to four levels of )DOT nesting are permitted. The same table cannot be processed recursively. The list of records must end with the )ENDDOT statement.

If the table was already open, it remains open after file tailoring with the CRP positioned at TOP. If it was not open, it is opened automatically and then closed upon completion of file tailoring.

Any of the other control statements can be used between the )DOT and the )ENDDOT control statements.

Example 1

This example takes the information from table ABC, and writes any blank table row as a blank line:

)DOT ABC
)SEL &LNAME = &Z && &FNAME = &Z
)BLANK 1
)ENDSEL
    &FNAME &LNAME
)ENDDOT

Example 2

This example takes the information from table ABC, and writes out the records containing the value in the dialog variable &VAR2, where the table variable VAR1 matches the current value in the dialog variable &VAR1:

)DOT ABC SCAN(VAR1,EQ)
&VAR2
)ENDDOT

)IF )ELSE

The relational-expression is evaluated for a true or false condition.

If the condition is true, then either the control-statement on the )IF control statement is processed or the next non-comment line is processed. The )ELSE statement, if one is present, is skipped.
If the condition is false, the control-statement or next non-comment line is skipped and the subsequent )ELSE statement, if one is present, is processed.

Up to 32 levels of )IF and )SEL nesting are permitted.

The control-statement can be any ISPF file tailoring control statement, except )CM (comment), which is ignored. Some control statements, namely )DO, )SEL, and )DOT require more than one input record. Similarly, the )IM control statement imbeds another ISPF skeleton member. The processing of the )IF or )ELSE statement is not completed until the control statement specified on the )IF or )ELSE statement is also completed.

Only a control statement can be included on the same input record after the THEN parameter or )ELSE control word. Put data records that are to be processed as part of the )IF or )ELSE on the next input record. The control-statement is optional on the same line as either the )IF or )ELSE control words, but a valid statement must be supplied for an )IF and )ELSE control statement before the end of the skeleton member. A severe error will occur if the control statement is missing after the THEN parameter or )ELSE control word. Use the )NOP control statement to provide a null statement.

Example 1

This example combines the )IF and )DO statements to process a block of input records when the variable RC has a value of zero, or another block of input records when its value is nonzero.

)IF &RC = 0 THEN )DO
. . .
)ENDDO
)ELSE )DO
. . .
)ENDDO

Example 2

This example sets the dialog variable RC back to zero when it has a value of 4. Note that the comment statement is ignored.

)IF &RC = 4 THEN
)CM RESET RETURN CODE TO ZERO
)SET RC = 0

)IM

The specified skeleton is imbedded at the point where the )IM statement is encountered. Up to 15 levels of imbedding are permitted.

The optional NT parameter indicates that no tailoring is to be performed on the imbedded skeleton. Because the NT parameter causes the data to be imbedded as it is, without any processing of control characters or control statements, using the NT option improves performance.

The optional OPT parameter indicates that the skeleton is not required to be present in the skeleton library. If OPT is coded and the skeleton is not present, no error indication is given, and the record is ignored. If OPT is not coded, and the skeleton is not present, a severe error occurs.

The EXT parameter enables the use of the extended built-in functions within the skeleton skel-name. The NOEXT parameter disables the use of the extended built-in functions. These two parameters only apply to the specified skeleton name. Nested imbeds do not inherit the state. Both parameters are optional. When neither the EXT or NOEXT parameter is specified, the ability to use the built-in functions is determined by the FTINCL service call:

Table 1. EXT and NOEXT, effect on built-in functions support
)IM control statement	FTINCL service
	Not specified	EXT
	Built-in functions supported?
Not specified	No	Yes
EXT	Yes	Yes
NOEXT	No	No

)ITERATE

The )ITERATE statement terminates the current iteration of the )DO structure and repeats the loop, providing any conditions that would cause the loop to terminate have not yet been reached. A severe dialog error will occur if the )ITERATE statement is used outside a )DO structure.

)LEAVE

The )LEAVE statement immediately terminates the innermost )DO statement. A severe dialog error will occur if the )LEAVE statement is used outside a )DO structure.

The optional DOT parameter permits the termination of the current table via the )DOT … )ENDDOT control statements. The )LEAVE DOT statement must be found within an active )DOT … )ENDDOT sequence.

)NOP

The )NOP control statement does not generate any output and can be used anywhere in a skeleton input file. It can be used as a null control-statement for either the )IF or )ELSE control statements.

)REXX )ENDREXX

The )REXX control statement is used to invoke REXX code from within a file tailoring skeleton. The REXX can be coded within the skeleton immediately after the )REXX control statement, or the name of a member containing a REXX exec can be supplied.

variable1 … variablen are optional parameters that specify the names of dialog variables to be passed to the REXX code for processing. Each variable can itself be a variable name, whose value is a list of one or more dialog variables, separated by either a space or a comma, that are to be passed to the REXX code.

rexxname specifies the name of a member in the standard search sequence used to load REXX programs. This member can contain interpreted REXX or compiled REXX. Compiled REXX can be either the output generated by the REXX compiler when using the CEXEC option, or a load module generated by link-editing the output generated by the REXX compiler when using the OBJECT option. This is an optional parameter.

If a percent sign (%) is specified before rexxname, it will bypass the attempt to load the REXX as a load module and attempt to load it directly from the standard SYSEXEC/SYSPROC allocations.

TSOENV indicates that you want ISPF to use the current TSO environment. If your dialog does an IRXINIT to create its own REXX environment, but this keyword is not specified, that environment is not used to process the REXX code. The REXX code is instead invoked in ISPFs REXX environment.

Note:

The REXX code cannot access any other dialog variables except those specified on the )REXX control statement.
The REXX code cannot issue requests for ISPF services.
REXX coded within the skeleton must be terminated by a )ENDREXX control statement within the same skeleton member.

ISPF dialog variables can be processed by file tailoring REXX code. Dialog variables are made available to the REXX code via the parameters specified on the )REXX control statement:

The variable values must be in character format when passed to file tailoring REXX code, and must remain in character format.

The ISPF module ISPFTRXV is used to make ISPF dialog variables available to the file tailoring REXX code, and to update the dialog variables after they have been processed by file tailoring REXX.

When the file tailoring REXX is interpreted REXX (that is, the REXX statements are coded directly in a skeleton or the member specified on )REXX control statement contains interpreted REXX), ISPF creates calls to ISPFTRXV to perform these tasks:

Set up corresponding REXX variables for the ISPF dialog variables before the file tailoring REXX is invoked.
Update the ISPF dialog variables with any changes made by the file tailoring REXX after it has finished.

To do this, ISPF generates these REXX statements before and after the supplied file tailoring REXX code:

    Call ISPFTRXV 'I'
    If rc=0 then do
    say 'ISPFTRXV Init failed rc='rc
    return
    end
    Call ft_0003B060
    Call ISPFTRXV 'T'
    If rc=0 then
    say 'ISPFTRXV Term failed rc='rc
    return
    ft_0003B060:
    ⋮
       file tailoring REXX code
    ⋮
    return

(Bold text indicates REXX code generated by ISPF.)

Note:

A trace i statement is also inserted into the REXX code generated by ISPF when the file tailoring trace command (ISPFTTRC) is used with the debug option.
The 11 or 12 lines of REXX code generated by ISPF before the supplied file tailoring REXX code and the line of REXX code generated by ISPF after the supplied file tailoring REXX code will affect the results obtained from the SOURCELINE function. For example using SOURCELINE() in interpreted file tailoring REXX code returns a value that is 12 or 13 more than the number of source lines of file tailoring REXX.

If the interpreted file tailoring REXX code uses the EXIT statement to terminate REXX processing, the termination call to ISPFTRXV generated by ISPF will not be executed. This means that any changes made to REXX variables will not be applied to the corresponding ISPF dialog variables. If you need to use the EXIT statement in your file tailoring REXX code and you want changes to be applied to the ISPF dialog variables, ensure that a termination call to ISPFTRXV (that is, Call ISPFTRXV 'T') is executed before the EXIT statement.

When the file tailoring REXX code is compiled REXX, ISPF does not create these initialization and termination calls to ISPFTRXV. Therefore, file tailoring developers must include these calls in their file tailoring REXX code.

ISPF provides these system dialog variables for processing errors and return codes in file tailoring REXX:

ZFTXRC: Available for file tailoring REXX code to pass a return code back to ISPF. Length is 2 bytes. The corresponding REXX variable is initialized with a value of 0.
ZFTXMSG: Available for file tailoring REXX to return a message ID to file tailoring and the invoking application. Length is 8 bytes. The corresponding REXX variable is initialized with a value of 8 blanks.

ISPF recognizes these return codes passed back by the file tailoring REXX code in the dialog variable ZFTXRC:

0: Successful operation.
8: File tailoring REXX defined failure. File tailoring continues.
other: Severe error in the file tailoring REXX. File tailoring terminates.

When control returns to ISPF after the file tailoring REXX code has executed, if ZFTXRC contains a return code of 8 and the value in ZFTXMSG is blank, then ZFTXMSG is set to ISPF222.

If the return code in ZFTXRC is other than 0 or 8, the FTINCL service terminates with a severe error condition. ISPF sets the ZERRMSG system variable using this search order:

If the value in ZFTXMSG is not blank when control returns to ISPF, it is used to set the ZERRMSG system variable. This allows the file tailoring REXX code to define the message to be used if a severe error occurs.
If the value in ZFTXMSG is blank when control returns to ISPF, ZFTXMSG and ZERRMSG are set to ISPF223. This is the default ISPF message for severe errors relating to file tailoring REXX.

If CONTROL ERRORS CANCEL is in effect, ISPF displays on the severe error panel the message indicated by the value of ZERRMSG.

)SEL )ENDSEL

The relational expression is evaluated for a true or false condition.

If the condition is true, the skeleton input records between the )SEL and the corresponding )ENDSEL are processed.
If the condition is false, these records are skipped.

Up to 32 levels of )SEL and )IF nesting are permitted. The list of records must end with an )ENDSEL statement.

Any of the other control statements can be used between the )SEL and the )ENDSEL control statements. For example, if you want to write information from a table only if variable ABC is set to the name of that table, specify:

)SEL &ABC = &TABNAME
)DOT TABNAME
   &FNAME &LNAME
)ENDDOT
)ENDSEL

The relational expression consists of a simple comparison of the form:

value1 operator value2

or a combination of up to eight simple comparisons joined by connectors. The system variable Z can be used to represent a null or blank value.

The allowable operators are:

EQ  or  =               LE  or  <=
NE  or  ¬=              GE  or  >=
GT  or  >               NG  or  ¬>
LT  or  <               NL  or  ¬<

The allowable connectors are | (OR) and && (AND). ISPF evaluates connected expressions from left to right and evaluates the connectors with equal priority.

Examples:

)SEL  &COND = YES
)SEL  &TEST1 ¬= &Z   |  &ABC = 5
)SEL  &TEST1 ¬= &Z  &&  &ABC = 5

)SET

)SET allows a value to be assigned to a dialog variable. The variable name should not be preceded by an ampersand, unless the variable name is itself stored as a variable. A blank is required between the variable and the equal sign and between the equal sign and the expression.

The expression can be specified in either of these ways:

 value1

 value1  operator  value2  operator  …  value31

where operator can be a plus sign ( + ) or a minus sign ( - ).

To assign a null value to a dialog variable, use the system variable &Z.

Example:

An input skeleton file contains:

)SET A = 1
)SET B = 2
)SET C = &A + &B
)SET D = &Z
A is &A, B is &B, C is &C, D is &D

The resulting output file contains:

A is 1, B is 2, C is 3, D is

)SETF

The )SETF control statement is the same as the )SET control statement, except that it does not require the use of the EXT parameter on either the FTINCL service or )IM control statement that is processing the skeleton to use any of the built-in functions. In other words, the extended built-in functions can always be used on the )SETF control statement.

The expression can be specified in either of these ways:

   value1

   value1  operator  value2  operator  …  value31

where operator can be a plus sign ( + ) or a minus sign ( - ). Each value of the expression can be a built-in function or a value.

If you need more arithmetic capabilities, use the &EVAL() built-in function (&EVAL()) or use the )REXX control statement to invoke a REXX exec.

Examples:

)SETF  TOTAL = &EVAL(&SUB1 * (&N-1)) + 2
)SETF NAME = &STR($FNAME &SNAME)

)TB

The )TB control statement has 3 forms:

Syntax - standard tabbing

Syntax - alternate tabbing: designated positions

Syntax - alternate tabbing: all positions

An exclamation point (!) is used as the default tab character for the )TB control statement.

It tabs the output record to the next tab stop and fills the intervening spaces with blanks. The next character following an exclamation point in the input record is put at the tab stop location in the output record. Up to 16 tab stops can be specified. A tab stop specifies a tab position in the output record, and must be in the range 1-255. The default is one tab stop at location 255.

When you use the standard tabbing syntax, )TB value1 … value16, and the tab stop value equals the current output position, the tabbing skips to the next tab stop value that is greater than the current output position. The input character following the tab character is then inserted into the position skipped to in the output record.

When you use alternate tabbing syntax, specified with an 'A' in the )TB tabbing syntax, and the tab stop value equals the current output position, the input character following the tab character is inserted into the current position in the output record. This allows you to write to the current position of the output record if a tab character in the input record is encountered at the same time as a tab stop is encountered in the output record.

The way you specify alternate tabbing syntax on the )TB control statement determines whether only designated or all tab stop values are affected, even if the tab stop value equals the current position in the output record when a tab character is encountered in the input record. If you specify:

   )TB value1A … value16A

only the tab stop values to which the character A is appended selectively cause tabbing to stop in any of those positions. If you specify:

   )TBA  value1 … value16

any tab stop value that equals the current position in the output record when a tab character is encountered in the input record causes tabbing to stop.

Be sure the character that you append for alternate tabbing is an uppercase A. Appending an A to the )TB control word (that is, )TBA ) has the same effect as appending an A to all individual tab stop values. When you use the )TBA control word, appending an A to an individual tab stop value has no additional effect.

Example 1:

This example uses the standard tabbing syntax:

An input skeleton file contains:

  )TB 5 10 20
  !ABCDE!F

After processing, the file-tailoring output record contains these characters:

Positions 1-4 contain the blanks inserted by the first tab operation.
Positions 5-9 contain ABCDE. Standard tabbing occurs between E and F because tab stop 10 is at the same (not greater than) position of the output record at which the tab character is encountered in the input record.
Positions 10-19 contain blanks inserted by the second tab operation.
Position 20 contains F.

Example 2:

This example uses alternate tabbing syntax for designated tab positions:

An input skeleton file contains:

  )TB 5 10A 20
  !ABCDE!F

After processing, the file-tailoring output record contains these characters:

Positions 1-4 contain the blanks inserted by the first tab operation.
Positions 5-10 contain ABCDEF. F immediately follows E because alternate tabbing is specified for tab position 10. This allows tabbing to stop in the current output record position (10) when the tab character was encountered in the input record.

Example 3:

This example uses the alternate tabbing syntax for all tab positions:

)TBA value1 … value16

An input skeleton file contains:

  )TBA 3 6 10
  !ABC!DEF!GH

After processing, the file-tailoring output record contains:

Positions 1-2 contain the blanks inserted by the first tab operation.
Positions 3-5 contain ABC. D immediately follows C because alternate tabbing is specified and a tab stop is set at the current output position (6).
Positions 6-8 contain DEF.
Position 9 contains a blank inserted by normal tabbing.
Positions 10-11 contain GH.