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.