18.1.1 Rules, Limitations and Guidelines
The following rules, limitations and guidelines apply to the use of the X_START facility:
No default value, remembered value, description or symbolic name can be more than 256 characters long.
All [ / / ] prompt requests must be precisely formatted [default/description/symbolic name] using the '/' character to delimit the areas between the [ ] characters.]
All { / / } prompt requests must be precisely formatted {default/description/symbolic name} using the '/' character to delimit the areas between the { } characters.
Special values *NONE and *PASSWORD may be used in the default and/or symbolic name section of any [//] or {//} prompt area. *NONE indicates that no value exists and/or that the prompt value should not be saved in file X_START.SAV. *PASSWORD indicates that the prompt is for a password field (i.e. that entry made into the prompt should not be readable) and that the value should not be stored in file X_START.SAV.
The correct format for a password field prompt is [*PASSWORD/description/symbolic name] or {*PASSWORD/description/symbolic name}. You cannot cause a password field to adopt a default value.
No more than 1024 symbolic names (and their associated values) can be stored in any X_START.SAV file.
X_START looks for (and saves) the file X_START.SAV into the current directory of the process invoking the X_START facility.
The X_START facility can extract the command line definition to be processed either directly from the icon command line or from a file.
To extract the command definition from a file, simply use the name of the file containing the command line definition prefixed by an '=' (equal) sign or an '@' (at) sign as a single argument to X_START. For example:
X_START %basepath%\x_lansa\execute\X_RUN
proc=[X/Process/PROCESS]
and
X_START =TEST.DTA
are functionally identical operations when TEST.DTA is a file that contains these 2 lines:
%basepath%\x_lansa\execute\X_RUN
proc=[X/Process/PROCESS]
The default characters that denote the start of a prompt are '[' and '{'. These may be altered by inserting the following into the current X_START.SAV file:
X_START_OPEN_BRACE1
y
or
X_START_OPEN_BRACE2
y
where y is the character you wish to use in place of the '[' or '{' characters. You should only alter the default value in extreme situations involving code page conflicts, etc.
The default characters that denote the end of a prompt are ']' and '}'. These may be altered by inserting the following into the current X_START.SAV file:
X_START_CLOSE_BRACE1
y
or
X_START_CLOSE_BRACE2
y
where y is the character you wish to use in place of the ']' or '}' characters. You should only alter the default value in extreme situations involving code page conflicts, etc.
The character that separates strings within a prompt is the forward backslash '/'. This may be altered by inserting the following 2 lines into the current X_START.SAV file:
X_START_SEPARATOR
y
where y is the character you wish to use in place of the '/' character. You should only alter the default value in extreme situations involving code page conflicts, etc.
The string "OK" appears by default on the OK button of the prompt dialogue. You can change this string by inserting the following 2 lines into the current X_START.SAV file:
X_START_OK
yyyy
where yyyy is the string that is to appear on the OK button. String yyyy should of course be sensibly sized.
The string "Cancel" appears by default on the Cancel button of the prompt dialogue. You can change this string by inserting the following 2 lines into the current X_START.SAV file:
X_START_CANCEL
yyyy
where yyyy is the string that is to appear on the Cancel button. String yyyy should of course be sensibly sized.
The string "Parameter Help" appears by default on the Parameter Help button of the prompt dialogue. You can change this string by inserting the following 2 lines into the current X_START.SAV file:
X_START_PARMHELP
yyyy
where yyyy is the string that is to appear on the Parameter Help button. String yyyy should of course be sensibly sized.
The string "General Help" appears by default on the General Help button of the prompt dialogue. You can change this string by inserting the following 2 lines into the current X_START.SAV file:
X_START_GENLHELP
yyyy
where yyyy is the string that is to appear on the General Help button. String yyyy should of course be sensibly sized.
The previous points mean that the symbolic names:
X_START_OPEN_BRACE1, X_START_OPEN_BRACE2, X_START_CLOSE_BRACE1, X_START_CLOSE_BRACE2, X_START_SEPARATOR, X_START_OK, X_START_PARMHELP, X_START_GENLHELP and X_START_CANCEL are reserved and should not be used in [//] or {//} prompts as symbolic names.Assembled commands are always assumed to be being used to invoked .EXE programs, so the string .EXE will be automatically added to final commands as appropriate.
The X_START.EXE program should only ever reside in the \X_LANSA\EXECUTE\ directory of the current LANSA system. Do not place it in any other directory.
A file named X_START.SDH may also optionally reside in the \X_LANSA\EXECUTE directory. This file is used to support parameter and general help text and is formatted:
HELP=XXXXXXXXXX
<lines of text>
HELP=XXXXXXXXXX
<lines of text>
where XXXXXXX is the symbolic name of the parameter to which the help text applies or the general help identifier of the prompt.For full working examples of prompted X_RUN commands you should refer to files X_START.001 -> X_START.010 in your \X_LANSA\SOURCE directory and to file X_START.SDH in your \X_LANSA\EXECUTE directory.
There is an optional merge file, which provides the ability for another program to dynamically provide values for symbolic names. Each line in the merge file has the format:
%<variable name>%=<value>
e.g. %proc%=MYPROC
The variable name must be 4 characters long followed immediately by an '='. The value is all the characters from the '=' to the end of the line. The variable name must not be a pre-defined variable name. This results in a fatal error at execution time.