SPFLite - V3.0.24069 2024-03-09

Syntax

Operands

 

Abbreviations and Aliases

 

SUBMIT can also be spelled as SUB

 

Description

The SPFLite SUBMIT primary command allows a program or batch file to be launched from SPFLite. Prior to executing the program or batch file, a copy of an entire edit file, or selected contents of it, are written to a temporary file. In particular, this means that a modified edit file need not be saved prior to being submitted; ‘temporary' changes can be made to a file, then the file may be submitted that included those temporary changes, and then finally those changes could be canceled, if desired.

Temporary files created by SPFLite are periodically removed. This cleanup occurs during SPFLite startup time, when all files in the SUBMIT Working Directory that match a file pattern of SUB*.* and are two or more days old are deleted. The user is free to manually delete these files sooner, if desired.

A number of submit codes are supported to provide arguments to the submit command. A submit code generally consists of a ~ tilde and a single letter (case insensitive), except for the ~K  and ~S codes that have an extended syntax. Note: Any submit code that represents or contains a directory path as a string will contain only that path, without any enclosing quotes, even if the path contains embedded blanks. It is the user's responsibility to enclose submit codes on the SUBMIT prototype command in quotes when there is a possibility that the values might have embedded blanks.

Submit codes may be specified anywhere on the SUBMIT prototype command as needed. It would be considered unusual for a SUBMIT prototype command to contain more than one instance of the same kind of submit code, but SPFLite does not prevent such usage.

A submit code can alternatively be coded with a ^ circumflex instead of a ~ tilde, such as ^R. When this is done, the given submit code essentially works the same way, but the string value that is substituted for it is converted to upper case. This may be useful when the submit prototype command launches a batch script, so that the case of certain batch script arguments can be ignored.

The defined submit codes are as follows:

~1, ^1  through  ~9, ^9

A specific argument number specified in the SUBMIT primary command that was enclosed in brackets; the enclosing argument brackets on the SUBMIT primary command are removed. For example, the primary command SUBMIT [one "two three"] causes the ~1 code to be replaced by the value of one and ^1 to be replaced by the value of ONE wherever they appear on the SUBMIT prototype command. Submit codes ~9 and ^9 are “catch-all” codes that represent argument 9 and beyond, if there are ten or more argument strings supplied.

~A, ^A

All arguments specified in the SUBMIT primary command that were enclosed in brackets; the enclosing argument brackets on the SUBMIT primary command are removed. For example, the primary command SUBMIT [one "two three"] causes the ~A code to be replaced by the value of one "two three" wherever ~A appears on the SUBMIT prototype command.

~C, ^C

The full path name of the configuration-files directory of SPFLite. A sample value for ~C would be “C:\Documents and Settings\George\My Documents\SPFLite”.

~D, ^D

The current directory date of the original file, in the ISO format YYYY-MM-DD.

~E, ^E

The full path name of the executables directory of SPFLite; the directory into which SPFLite was installed. A sample value for ~E would be “C:\Program Files\SPFLite”.

~F, ^F

The simple file name of the original file without the path or extension. When submitting from the clipboard, this will be an empty string. For file name C:\ONE\TWO.TXT, ~F contains TWO.

~I, ^I

The full path and file name of the temporary file containing the selected contents of the current EDIT (or BROWSE or Clipboard) session from which the SUBMIT primary command was issued. The ~I code must be present on the SUBMIT prototype command line for the submit process to operate according to its intended purpose. It would be considered unusual for a SUBMIT prototype command not to contain the ~I code, but SPFLite does not enforce such usage. Names for temporary submit files have the general form SUBMIT_JOB12345.TXT.

~J, ^J

A job ID, formatted as JOBnnnnn. JOB is constant and nnnnn will be an incrementing number  starting at 1 and incremented by 1 for every submitted job. The ~J counter is kept in the SPFLite CFG configuration file as the persistent value JobNumber, and is installation-initialized to 1. This provides a means of assigning every job a unique job number and a unique file name for the temporary files that get created.

~K(ISODATE), ^K(ISODATE)

The current date when batch process submitted, in the format YYYY-MM-DD.

~K(ISOTIME), ^K(ISOTIME)

The current time when batch process submitted, in the format HH:MM:SS.

~K(primitive), ^K(primitive)

Any of the keyboard primitives which emit data may be used, as well as any key definitions which contain either un-bracketed strings (like primary commands) or those bracketed in [ ] brackets (i.e. simple keyboard text strings. Keys are specified by their official name, which can be seen when the key is selected in the KEYMAP dialog. For example, ~K(F2) substitutes the string assigned to the F2 key. For key variations, prefix the keyname with the letters S,C or A (Shift, Control or Alt) in any combination followed by a – dash: ~K(S-F2) for Shift-F2; ~K(CA-Home) for Control-Alt-Home.

~M, ^M

Provides extended file Mode information. This submit code may be passed to any desired program, but is intended for use with a future version of the SPFSUBMIT.EXE program. The Mode information can be used to handle cases where SUBMIT is used with files of non-standard file formats, character sets, etc. This information is taken from the current Profile values. When a new file is being submitted, or a file is submitted from the File Manager using the J line command that has no existing profile, the DEFAULT profile's values are used. When the  ~M or ^M code is used, a set of 7 command-line parameters are generated, in the following format:

       -SUB:m -EOL:eee -LEN:nnn -FMT:fff -SRC:sss -TAB:ttt -EBC:D 

 where

-SUB:m is a Submit method code. 

J = submitted from File Manager with J line command

S = submitted from edit session with SUBMIT command

-EOL:eee is the current EOL setting, such as CRLF

-LEN:nnn is the current LRECL setting, which is 0 for a standard text file

-FMT:fff is the current RECFM setting, which is U for a standard text file

-SRC:sss is the current SOURCE setting, which is ANSI for a standard text file

-TAB:ttt is the current XTABS setting

~N, ^N

The full, complete name of the original file, path included. For file name C:\ONE\TWO.TXT, ~N contains C:\ONE\TWO.TXT. 

Note: Since SPFLite has opened, and has access to the original file during the EDIT or BROWSE session, it could present run-time issues if any user program or script tried to open and modify the same original file while SPFLite still had ‘ownership' of it. It is possible such usage might succeed, but SPFLite cannot guarantee the outcome under such circumstances. Users are advised to treat the ~N code as an “information-only” value and not attempt to open the file during the time SPFLite has the underlying EDIT file open.

~P, ^P

The path of the directory containing the original file. When submitting from the clipboard, this will an empty string. For file name C:\ONE\TWO.TXT, ~P contains C:\ONE.

~R, ^R

When specified, ~R is expanded to the full path name of a temporary file (a “Response file”) used to provide job results status from the user's job submission procedure. This temporary file name will have an SPFLite provided name incorporating the current job number, and an extension of .TXT. These temporary files are located in the user-specified SUBMIT working directory. When the SUBMIT prototype command contains the ~R code, SPFLite will monitor the temporary Results file for any changes to it, and will display the lines of this file in a popup display. The user is responsible for formatting and writing a brief, meaningful message to this file. Use of the ~R response file code is optional; when omitted; SPFLite makes no attempt to monitor for a Results file. One source for creating the Results file is the standard output of the SPFSUBMIT utility program if redirected to a text file. Note that SPFLite will create this as an empty file when ~R or ^R are specified; and then it monitors that file name for any file-create or file-update activity. Names created as response-file names have the general form SUBRESULTS_JOB12345.TXT.

~S(name), ^S(name)

When specified, the string value of the defined SET variable name is substituted. See the SET primary command for more information on defining SET variables.

~T, ^T

The current directory time of the original file, in the ISO format HH:MM:SS.

~X, ^X

The file extension of the original file, including the leading dot, or else an empty string if file has no extension. When submitting from the clipboard, this will be an empty string. For file name C:\ONE\TWO.TXT, ~X contains .TXT.

~Z, ^Z

The contents of the SUBARG string. A SUBARG string is defined on the PROFILE-level for a given file type, and is defined by edit primary command SUBARG. SUBARG takes one operand, a submit argument string. This value must be quoted if it contains embedded blanks; any of the 3 quote types are permitted. The contents of SUBARG may be displayed by issuing SUBARG with no operand, or by issuing the PROFILE command to see this value along with all other profile settings. When a SUBARG value for a given file type is undefined, the value of ~Z is OFF, as a 3-character upper case value. The value is undefined by default and can be undefined by issuing SUBARG OFF. Thus, OFF (in any upper or lower-case spelling) is reserved. Any other SUBARG value may be set, and is accepted as-is (the value is not upper-cased). Note that if you actually wish to use OFF and ON as values, that is possible, except that OFF will always appear in upper case, while an ON value, if  used, appears just as you enter it on the SUBARG command. It is not possible to define the ~Z code as an empty string. The value OFF is handled the way it is to make checking for it easier in batch scripts.

Note: What would the SUBARG ~Z value be used for?  The submit edit file's extension is available from the ~X code, so that can be used to tailor a submit script based on file type. Suppose a group of related files had some common requirement; then, the file type alone might not be enough to make the required distinction. Or, perhaps files are being submitted that do not have a file extension. The SUBARG value provides a means to tailor the submit process in these special circumstances.

See SUBARG - Set Default SUBMIT Argument and Working with the SUBMIT Command for more information.

Examples

To submit all of the data as a batch process:

SUBMIT

To submit lines between labels .START and .END as a batch process:

SUBMIT .START .END

To submit all of the data to a batch process, with the arguments "ONE" and "TWO THREE":

SUBMIT [ONE "TWO THREE"]

To submit only non-excluded lines as a batch process:

SUBMIT NX

To submit only excluded lines not having tag :T between lines .A and .B as a batch process:

SUBMIT X :\T .A .B

Created with the Personal Edition of HelpNDoc: Effortlessly Edit and Export Markdown Documents