Define Substitution Variables Used in a List

When the option to 'Define substitution variables used in list' is chosen from the Work with Export List Menu a screen similar to the following example is used to manipulate the export list:

DC@P620011        Define Substitution Variables                                                                                                                                                                         List       : TEST2   Export details in compiled form                                                                                            Variable  Substitution value / Default value       Prompt user        Name    Prompt text to display if prompt req  When importing    $$DTALIB$$ _______________________________________      Y            Specify library to which database files are to be imported                                                                            $$SYSNAM$$ _______________________________________      Y            Specify the 4 letter prefix/name of your system                                                                                          _______  ________________________________________      _             ____________________________________________________                                                                                                                                                  Fnn=Help  Fnn=Exit  Fnn=Cancel  Fnn=Messages

A substitution value is a symbolic name that can be used:

• As the target library for any LANSA file definition being imported in a machine. The facility that allows LANSA file definitions to be included into an export list is described in Add Files to the List.

• As the target library for any non-LANSA object being imported into a machine. The facility that allows non-LANSA objects to be included into an export list is described in Add Non-LANSA Objects to the List.

• Anywhere in an IBM i or CPF command that is to be executed before or after an import run. The facility that allows commands to be defined for execution before or after an import run is described in a later section of this chapter.

Substitution variables are useful because they let the importing site specify what value should actually be used for some activity, rather than the exporting site having to know in advance and 'hard-code' into the export list what the value should be.

For example, an exporting site can indicate that a physical file should be imported into a library called QGPL. Thus the importer has no chance to actually change the library name when importing the information in his/her system.

However, by using a substitution variable, the exporter can indicate that the file should be imported into a 'variable' library called $$DTALIB$$. When the job is run, LANSA will ask the importer what value should actually be used in place of variable $$DTALIB$$.

Substitution variables names always have the format:

$$XXXXXX$$

where XXXXXX is any set of non-blank letters or numbers.

Every export list contains one special substitution variable called $$DTALIB$$ which cannot be deleted. This is the default variable used by LANSA when importing file definitions into any system.

As many other variables as required can be defined within an export list provided that their names are unique within the list and they have the correct name format of $$XXXXXX$$.

An import job produces a report just like an export job does. All interactions with the importer, with regard to substitution variables, are recorded on the report.

By using the 'Define substitution variables in list' facility it is possible to:

• Define new substitution variables.

• Alter details of existing substitution variables.

• Delete existing substitution variables.

To delete an existing variable, simply blank out/field exit over all details of the variable and press enter.

To define a new variable or alter an existing variable, enter/modify details as follows:

• The Variable Name must be in the form $$XXXXXX$$ where XXXXXX is any combination of numbers and letters (must be uppercase). Preferably the xxxxxx portion should be meaningful in some way.

• The Substitution Value / Default Value only demands mandatory entry if the variable is not to be prompted on import (see 'Prompt When Input' explanation below). If there is to be no prompt on import, the importing user will not be asked to supply a value for the variable and the value specified here will be used.

• When used with a prompted variable, the value entered here is the default value used if the importer either does not reply to the message, or else indicates that the default value should be used.

• The Prompt When Input value indicates whether or not the importing user should be prompted to supply a value for the variable.

• Enter 'Y' to indicate that the importer should be prompted. In this case prompt text will be required.

• Leave blank or enter 'N' to indicate that the importer should not be prompted. In this case a substitution / default value for the variable will be required.

• The Prompt Text specifies what message should be sent to the importer as a prompt for the variable when running an import job. Prompt text must be specified when a variable is prompted. The message should be as meaningful as possible in the space provided and normally ends with a question mark (?).

• A special feature allows the substitution / default variable to be specified as a LANSA system variable name. This means that more flexibility can be introduced into the preparation of export lists for import with no operator intervention.

This example uses the shipped system variable *PARTDTALIB (Partition Data Library) as a default value for the substitution value. When this list is imported this system value will be set to the correct library name (e.g.: DC@MODLIB) and then the operator will be prompted with DC@MODLIB as the default reply because 'Prompt' is Y (yes).

Variable  Substitution value / Default value    Prompt user   Name    Prompt text to display if prompt req  When importing     $$DTALIB$$ *PARTDTALIB                                   Y     Specify library into which database files are to be imported

However, this example uses the shipped system variable *PARTDTALIB, but specifies N (no) for 'Prompt'. This means that the substitution value will be set to the partition data library name and then the import will proceed without asking the operator to confirm this value.

Variable   Substitution value / Default value    Prompt user   Name     Prompt text to display if prompt req  When importing     $$DTALIB$$ *PARTDTALIB                                   N   Specify library into which database files are to be imported

Any shipped LANSA system variable that is evaluated by program M@SYSVAR, or any user defined system variable at all, can be used in this manner.

Only alphanumeric system variables up to a maximum length of 50 characters should be used this way.