17.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.