xcall MIAMEX, MX_NXTCMD, cmdline, status {,flag}

This operation returns (and in doing so, by-passes) the next line of the current command (.CMD or .DO) file.   It is used in the implementation of GOTO.LIT in order to scan the command file for labels.

Parameters

cmdline should be a string variable long enough to return any expected command line.

status is a floating-point return code indicating the success of the operation. A zero value indicates that either no command file is running, or the end of the current command file has been reached. A non-zero value indicates success, in which case cmdline contains the text of the command line.

If flag (Num) is specified and evaluates to a non-zero value, then the next line of the command file (returned in cmd) will not be removed from the current command file—i.e., a non-destructive read.

Comments

This function is used in the implementation of GOTO.LIT in order to skip over the command line contents up to the target label. The technique can also be useful in a case where you want to effectively abort a command file execution in response to some data or environmental condition, perhaps chaining to another command file instead.

History

2010 June, A-Shell 5.1.1182:  Support returning data into dynamic variables, such that they expand as needed. Previously, the output data was being truncated to the current size of the variable, or 0 for uninitialized

2009 September, A-Shell 5.1.1160:  MX_NXTCMD now supports returning data into dynamic variables, such that they expand as needed. Previously, the output data was being truncated to the current size of the variable, or 0 for uninitialized.

2009 May, A-Shell 5.1.1150:  Add flag parameter.