Program and Environment Control

Reference Section

_arg_count
_arg_next
_arg_nth
_arg_progname
_arg_reset
cmdln_next
cmdln_start
_copy_envblk
_create_envblk
_environ_len
_environ_size
_exec_prog
_exec_proge
_exec_sys
_exec_syse
_exit_to_dos
_get_curenvseg
_get_dosenvseg
_get_env
_get_envseg
_get_parenvseg
_get_psp
_get_rootenvseg
_reset_argtbls
_reset_cmdln
_set_argtbls
_set_cmdln
_set_env

_arg_count


Descrip
Returns the number of command line arguments.

Syntax
#include <progctl.h>
int _arg_count(void);

Returns
Number of command line arguments.
Notes
This function returns the number of arguments on the command line. 0 is returned only if the command line contains no arguments.

Arguments are parsed at the current command line address using the syntax defined by the currently installed parsing tables. The address of the command line is maintained in cmdln_start and cmdln_next. It may be set directly or by calling _set_cmdln or _reset_cmdln. Parsing tables may be specified by calling _set_argtbls or _reset_argtbls.

WARNING! This function uses the _psp global variable in all models except TINY. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   char argbuf[20];
	   char args;
	   _put_str("Number of command line args: "); 
	   args = _arg_count();
	   _put_str(_ui_to_dec(args, argbuf));
	   _put_newline();
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char str[] = "Number of command line args: ";
	   char argbuf[20];
	   ...
	   lea si,str	/* SI = offset of str */
	   put_str();	/* display str */
	   arg_count();	/* CX = number of cmdln args */
	   lea si,argbuf/* SI = offset of buffer */
	   mov ax,cx	/* AX = number of arguments */
	   ui_to_dec();	/* int -> "string" */
	   put_str();	/* display number of args */
	   ...
	}

Source file _PCARCNT.ASM ASM equiv ARG_COUNT

_arg_next


Descrip
Returns the next command line argument.

Syntax
#include <progctl.h>
char *_arg_next(char *buffer, char *chr)

Returns
A pointer to buffer.
buffer next command line argument
chr terminating character

NULL if no more arguments exist.
chr undefined

Notes
This function locates the next command line argument and copies it into buffer in ASCIIZ format. In addition, the most significant terminating character following the argument is returned in chr. The first command line argument is returned if no arguments were previously returned by _arg_next or _arg_nth; otherwise, the argument is returned which follows the last argument returned by _arg_next or _arg_nth. NULL is returned if no arguments remain on the command line.

Arguments are parsed at the current command line address using the syntax defined by the currently installed parsing tables. The address of the command line is maintained in cmdln_start and cmdln_next. It may be set directly or by calling _set_cmdln or _reset_cmdln. Parsing tables may be specified by calling _set_argtbls or _reset_argtbls.

WARNING! This function uses the _PSP global variable in all models except TINY. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   char *argptr;
	   char chr, argbuf[20];
	   ...
	   if ((argptr = (char *)_arg_next(argbuf, &chr)) != NULL)
	      _put_str(argptr);
	   else
	      _put_str("No arguments encountered.\n\r");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str = "No arguments encountered.\n\r";
	   char argbuf[20];/* assume cmdln arg is char * type */
	   ...
	   lea si,argbuf/* SI = offset argbuf */
	   arg_next();	/* is there another argument */
	    jc label_100/*   n: display message */
	   put_chr();	/* put terminating character */
	   put_newline();
	   jmp short label_200
	label_100:
	   mov si,str 	    /* SI = offset of str */
	label_200:
	   put_str();	/* display str or arg */
	   ...
	}

Source file _PCARNXT.ASM ASM equiv ARG_NEXT
See also
_arg_count, _arg_nth, _arg_reset, _set_argtbls, _set_cmdln

_arg_nth


Descrip
Returns a specified command line argument.

Syntax
#include <progctl.h>
char *_arg_nth(char *buffer, int n, char *chr);

Returns
A pointer to buffer.
buffer nth command line argument
chr terminating character

NULL if no nth argument exists.
chr undefined
Notes
This function locates the nth command line argument and copies it into buffer in ASCIIZ format. In addition, the most significant terminating character following the argument is returned in chr. NULL is returned if no arguments remain on the command line. The first argument is argument 1.

Arguments are parsed at the current command line address using the syntax defined by the currently installed parsing tables. The address of the command line is maintained in cmdln_start and cmdln_next. It may be set directly or by calling _set_cmdln or _reset_cmdln. Parsing tables may be specified by calling _set_argtbls or _reset_argtbls.

This function does not support an argument number of zero (unlike the C convention). The name of the executing program may be obtained by calling _arg_progname.

C/C++ Example
	{
	   char argbuf[80], chr;
	   char *cmdarg;
	   if ((cmdarg = (char *)_arg_nth(argbuf, 2, &chr)) == NULL)
	      _put_str("\n\r2nd argument not found.");
	   else
	   {
	      _put_str("\n\rSecond argument: ");
	      _put_str(cmdarg);
	      _put_str("\n\rTerminating character: ");
	      _put_chr(chr);
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   char argbuf[20];	/* assume char * type arguments */
	   ...
	   lea si,argbuf/* SI = offset argbuf */
	   mov al,2	/* AL = argument to find */
	   arg_nth();	/* does argument exist? */
	    jc label_100/*   n: display message */
	   put_chr();	/* put terminating character */
	   put_newline();
	   jmp short label_200
	label_100:
	   str = "No arguments encountered.\n\r";
	   mov si,str	/* SI = offset of str */
	label_200:
	   put_str();	/* display str or arg */
	   ...
	}

Source file _PCARNTH.ASM ASM equiv ARG_NTH
See also
_arg_next

_arg_progname


Descrip
Returns the name and path of the executing program.

Syntax
#include <progctl.h>
char *_arg_progname(char *buffer);
Returns
A pointer to buffer.
bufferprogram pathname string

NULL if the program name does not exist.

Notes
This function returns the name and path of the executing program in buffer. The returned pathname includes a drive specifier, full path, program filename, and a terminal NULL. This information is retrieved from the end of the inherited environment and is usually available under versions of DOS starting with DOS 3.0. If the pathname information is not available for any reason, a NULL is returned and a NULL string is placed in buffer.

The version variables _osmajor and _osminor must be properly initialized prior to calling this function. When using Spontaneous Assembly for C/C++, these variables are supplied and initialized by the compiler instead of the Spontaneous Assembly library.

WARNING! This function uses the _PSP global variable in all models except TINY. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   char argbuf[80], *argptr;
	   _put_str("Program name: ");
	   if((argptr = _arg_progname(argbuf)) != NULL)
	      _put_str(argptr);
	   else
	      _put_str("Unable to find program name!\n\r");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char argbuf[80], *str;
	   ...
	   str = "Program name: ";	  	 
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display str message */
	   lea si,argbuf/* SI = offset of argbuf */
	   arg_progname();    /* is there a program name? */
	    jnclabel_200/*   y: go display */
	label_100:	 	/*   n: display error msg */
	   str = "Unable to find program name! \n\r";
	   mov si,str	/* SI = offset of str */
	label_200:
	   put_str();	/* display msg or prog name */
	   ...
	}

Source file _PCARPRG.ASM ASM equiv ARG_PROGNAME

_arg_reset


Descrip
Resets the current command line argument pointer.

Syntax
#include <progctl.h>
void _arg_reset(void);

Returns
No return value.
cmdln_start a pointer to the beginning of the current command line

Notes
This function resets the current command line argument pointer to the beginning of the command line. This causes the next call to _arg_next to return the first command line argument.

The starting address of the command line is maintained in cmdln_start. It may be set directly or by calling _set_cmdln or _reset_cmdln.

C/C++ Example
	{
	   char *argptr;
	   char chr, argbuf[20];
	 
	   if ((argptr = _arg_next(argbuf, &chr)) != NULL)
	      _put_str(argptr);/* display argument */
	   else	 	/*   (assume char *) */
	      _arg_reset();/* reset argument pntr to 
	                 beginning of command line */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char argbuf[20];
	   ...
	   lea si,argbuf/* SI = offset argbuf */
	   arg_next();	/* is there another argument */
	    jc label_100/*   n: reset arg pointer */
	   put_str();	/*   y: display argument */
	   put_chr();	/* put terminating character */
	   jmp short label_200
	label_100:
	   arg_reset();	/*   n: reset arg pointer */
	label_200:
	   ...
	}

Source file PCARRST.ASM ASM equiv ARG_RESET
See also
_arg_next, _reset_cmdln, _set_cmdln

cmdln_next


Descrip
(Variable) Indicates the offset of the next command line argument.

Syntax
#include <progctl.h>
extern char *cmdln_next;

Notes
This char pointer variable contains the offset of the first byte past the last command line argument which was returned using _arg_next or _arg_nth. The offset is an offset within the command line segment specified by cmdln_start. If no arguments have been returned from the command line, this variable contains the offset of the start of the command line. This variable is initialized to 0x81.

This variable may be modified by calling _set_cmdln or _reset_cmdln. It may also be modified directly.

Source file PCCMDLN.ASM ASM equivâ
See also
_arg_next, cmdln_start

cmdln_start


Descrip
(Variable) Indicates the starting address of the command line.

Syntax
#include <progctl.h>
extern char far *cmdln_start;

Notes
This char far pointer contains the starting address of the command line buffer. This is the buffer from which command line arguments are extracted using _arg_next and _arg_nth or counted using _arg_count. The high order word contains the segment address, and the low order word contains the offset. If the high order word is -1, then the segment address of the command line is assumed to be the segment address of the PSP. This variable is initialized to 0xFFFF:0081, which causes the _arg_... functions to parse the program command line at offset 0x81 within the psp.

This variable may be modified by calling _set_cmdln or _reset_cmdln. It may also be modified directly. If this variable is modified directly, the cmdln_next variable must be updated at the same time.

Source file PCCMDLN.ASM ASM equivâ
See also
_arg_next, cmdln_next

_copy_envblk


Descrip
Makes a copy of an environment block.

Syntax
#include <progctl.h>
segaddr _copy_envblk(segaddr env, segaddr buffer, unsigned int size);

Returns
Segment address of copied environment string.
buffer the copied environment

Notes
This function makes a copy of the environment block at env. The copy is placed in buffer and has approximately size-16 bytes of total environment space. The segment address of the copied environment string is returned.

The copied environment in buffer includes a simulated DOS Memory Control Block just below the environment information. This allows any of the Program Control unit environment functions to manipulate the copied environment using the segment address returned by this function. The copied environment may also be modified and passed to a child program via _exec_proge or _exec_syse.

WARNING! buffer must always be at least two paragraphs larger than the environment block being copied, or data following buffer will be overwritten. The size of the original environment block may be determined using the _environ_size function.

WARNING! The results are undefined if env is invalid.

C/C++ Example
	{
	   unsigned env_size;
	   segaddr env_seg, new_seg;

	   env_seg = _get_envseg(_get_psp()); /* env_seg=programs seg */
	   env_size = _environ_size(env_seg); /* find size of env_seg */
	   if(allocmem(((env_size+100)/16), &new_seg) != -1)
	      _put_str("Error allocating memory to copy environment!");
	   new_seg = _copy_envblk(env_seg,new_seg,env_size+100);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char msg[] = "Error allocating memory to copy environment!";
	   segaddr env_seg, new_seg;
	   unsigned env_size;
	   ...
	   get_psp();	/* get program's seg prefix */
	   get_envseg();	/* get programs environment */
	   mov env_seg,dx/* save prog's segment */
	   environ_size();    /* find environment size */
	   mov env_size,cx/* save env's size */
	   if (allocmem(((env_size+100)/16), &new_seg) != -1)
	       {
	   	  lea  si,msg/* SI = offset of str */
	   	  put_str();/* display error msg */
	       }
	   else
	       {
	   	  mov dx,env_seg  /* DX = seg of env to copy */
	   	  mov es,new_seg  /* ES = seg to copy to */
	   	  mov cx,env_size /* CX = size of env to copy */
	   	  copy_envblk();
	   	  mov new_seg,dx  /* save seg of environment */
	       }
	   ...
	}

Source file _PCCPYEN.ASM ASM equiv COPY_ENVBLK
See also
_create_envblk, _environ_size

_create_envblk


Descrip
Creates an empty environment block.

Syntax
#include <progctl.h>
segaddr _create_envblk(segaddr buffer, unsigned int size);

Returns
Segment address of the new empty environment string in buffer.
buffer the empty environment block

Notes
This function creates an empty environment block in buffer and returns the segment address of the environment. This empty environment block has approximately size-16 bytes of total environment space available to it.

The empty environment created in buffer includes a simulated DOS Memory Control Block just below the environment information. This allows any of the Program Control unit environment functions to manipulate the created environmentusing the returned segment address. This environment may also be modified and passed to a child program via _exec_proge or _exec_syse.

WARNING! This function uses the _psp global variable in all models except TINY. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	void *fcpy_env;
	segaddr new_seg;

	   _put_str("Creating environment block... (malloc)");
	   if ((fcpy_env = (char *)malloc(31000 + 50)) == NULL)
	      _put_str("Error allocating enough memory\
	   	  to \"create\" an environment");
	   else
	   {
	      new_seg = _ptr_to_seg(fcpy_env);
	      new_seg = _create_envblk(new_seg,31000);
	   /* new_seg = segment address of created envblk */
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char str[] = "\n\rCreating env block... (dos_malloc)"; 
	   segaddr new_seg;
	   ...
	   lea si,str	/* SI = offset of str */
	   put_str();
	   mov ax,0x7940/* 31040 bytes */
	   dos_malloc();	/* allocate DOS memory */
	    jnc label_010
	   exit(1);	/* error allocating DOS space */
	label_010:
	   mov es,dx	/* ES = segment of DOS block */
	   mov cx,31000
	   create_envblk();/* create env block */
	   mov new_seg,dx/* save segment of new envblk */
	   ...
	}

Source file _PCCRTEN.ASM ASM equiv CREATE_ENVBLK
See also
_copy_envblk

_environ_len


Descrip
Returns the length of an environment string.

Syntax
#include <progctl.h>
int _environ_len(segaddr env);

Returns
The length of the entire environment string at env, in bytes.

Notes
This function returns the length of the entire environment string at env. The environment string is made up of NULL terminated variable strings, the last of which is followed by an additional NULL character. The returned length includes the double NULL termination characters but does not include the environment tail.

WARNING! The results are undefined if env is invalid.

C/C++ Example
	{
	   unsigned env_len;
	   char outstr[80];
	   ...
	   env_seg = _get_envseg(_get_psp());/* get programs env seg */
	   env_len = _environ_len(env_seg);/* get env's length */
	   _put_str(_ui_to_dec(env_len, outstr));
	   	  	 	/* display length in bytes */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char outstr[80];
	   ...
	   get_psp();	/* get PSP */
	   get_envseg();	/* get segment of program */
	   environ_len();	/* get env length */
	   mov ax,cx	/* AX = length in bytes */
	   lea si,outstr /* SI = offset of outstr */
	   ui_to_dec();	/* convert unsigned to "string" */
	   put_str();	/* display length in bytes */
	   ...
	}

Source file _PCENVLN.ASM ASM equiv ENVIRON_LEN
See also
_environ_size

_environ_size


Descrip
Returns the size of an environment block.

Syntax
#include <progctl.h>
int _environ_size(segaddr env);

Returns
The size of the environment block at env, in bytes.

Notes
This function returns the total number of bytes allocated to the environment block at env, including the environment string, environment tail, and available environment space.

WARNING! The results are undefined if env is invalid.

C/C++ Example
	{
	   unsigned env_size;
	   char outstr[80];
	   segaddr = env_seg;
	   ...
	   env_seg = _get_envseg(_get_psp()); /* get program's envseg */
	   env_size = _environ_size(env_seg); /* get env's size */
	   _put_str(_ui_to_dec(env_size, outstr)); /* display env size */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char outstr[80];
	   ...
	   get_psp();	/* get PSP */
	   get_envseg();	/* get segment of program */
	   environ_size();    /* get env size */
	   mov ax,cx	/* AX = size in bytes */
	   lea si,outstr/* SI = offset of outstr */
	   ui_to_dec();	/* size -> "string" */
	   put_str();	/* display size in bytes */
	   ...
	}

Source file _PCENVSZ.ASM ASM equiv ENVIRON_SIZE
See also
_environ_len

_exec_prog


Descrip
Executes a program.

Syntax
#include <progctl.h>
int _exec_prog(char *pathname, char *cmdline);

Returns
The child program's program termination code and ERRORLEVEL if the child program was successfully executed (the high byte contains the termination code; the low byte contains the ERRORLEVEL).

-1 if an error occurred.
e_code error code

Notes
This function executes the program specified in pathname using the command line arguments in cmdline. An exact copy of the current program environment is passed to the child program. When the executed program terminates, the child program's ERRORLEVEL is returned in the low byte and the termination code is returned in the high byte of the return value. If the specified child program cannot be executed, -1 is returned and e_code contains the error code.

pathname must contain the path and name of the file to be executed. The filename must include either an .EXE or .COM extension. A partial or full path may be included, but only the specified directory is searched for the file. If no directory or disk drive is specified, the current working directory on the active drive is the only directory searched.

cmdline must contain any command line arguments which are to be passed to pathname. The length of cmdline is limited to 127 bytes including the terminating NULL.

The following symbolic constants (defined in PROGCTL.H) identify the termination codes which may be returned in the high byte of the return value after the child program has been successfully executed:

TERM_NORMAL(0x0000) Normal termination
TERM_CBREAK(0x0100) Ctrl-break termination
TERM_CRITICAL(0x0200) Critical device error
TERM_TSR (0x0300) TSR termination (DOS function 0x31)

_exec_sys may be used to execute a program anywhere in the current path without specifying a .EXE or .COM extension for the name of the program.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

WARNING! This function requires approximately 250 bytes of stack space.

C/C++ Example
	{
	   char progname[82];
	   char cmdln[82];
	   unsigned termcode;
	   _put_str("Program name? ");
	   _get_str(progname,80);
	   _put_str("Command line? ");
	   _get_str(cmdln,80);
	   if(termcode = _exec_prog(progname, 0) == -1)
	      _put_str("ERROR  .xxx (extension missing)\n\r"); 
	   termcode &= 0xFF00;	/* strip level code */
	   switch(termcode)
	   {
	      case TERM_NORMAL: _put_str("Normal termination\n\r");
	         break;
	      case TERM_CBREAK: _put_str("Ctrl-break termination\n\r");
	         break;
	      case TERM_CRITICAL:_put_str("Critical device error\n\r");
	         break;
	      case TERM_TSR: _put_str("TSR termination...\n\r"); break;
	      default: _put_str("Invalid term code.\n\r"); break;
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char progname[] = "PROGNAME.EXE";/* program to execute */
	   char cmdln[] = {0};/* no cmdln options */
	   char *str;
	   ...
	   pushss
	   pop es	 	/* ES = SS (progname on stack) */
	   lea di,progname/* DS:SI -> program name */
	   lea si,cmdln/* ES:DI -> command line */
	   exec_prog();
	    jc label_060/* go handle error condition */
	   cmp al,-1	/* missing extension? */
	    jnelabel_010/*   n: find/display term code */
	   str = "\n\rERROR: missing extension";
	   mov si,str	/* DS:SI -> str */
	   jmp short label_050
	label_010:
	   cmp ah,TERM_NORMAL/* Normal termination? */
	    jnelabel_020/*  n: try next */  
	     str = "\n\rNORMAL termination\n\r";
	   mov si,str	/* DS:SI -> str */
	   jmp short label_050	  
	label_020:
	   cmp ah,TERM_CBREAK/* Control Break termination? */
	    jnelabel_030/*   n: try next */
	   str = "\n\rCONTROL BREAK termination\n\r";
	   mov si,str	/* DS:SI -> str */
	   jmp short label_050/* continue */
	label_030:
	   cmp ah,TERM_CRITICAL /* CRITICAL termination? */
	    jnelabel_040/*   n: try next */
	   str = "\n\rCRITICAL termination\n\r";
	   mov si,str	/* DS:SI -> str */
	   jmp short label_050
	label_040:
	   cmp ah,TERM_TSR/* TSR termination? */
	    jnelabel_060/*   n: continue */
	   str = "\n\rTSR termination\n\r";
	   mov si,str	/* DS:SI -> str */
	label_050:
	   put_str();	/* display termination result */
	label_060:
	   ...
	}

Source file _PCEXPRG.ASM ASM equiv EXEC_PROG
See also
_exec_prog, _exec_sys

_exec_proge


Descrip
Executes a program using a specified environment.

Syntax
#include <progctl.h>
int _exec_proge(char *pathname, char *cmdline, segaddr env);

Returns
The child program's program termination code and ERRORLEVEL if the child program was successfully executed (the high byte contains the termination code; the low byte contains the ERRORLEVEL).

-1 if an error occurred.
e_code error code

Notes
This function executes the program specified in pathname using the command line arguments in cmdline. An exact copy of the environment at env is passed to the child program. When the executed program terminates, the child program's ERRORLEVEL is returned in the low byte and the termination code is returned in the high byte of the return value. If the specified child program cannot be executed, -1 is returned and e_code contains the error code.

pathname must contain the path and name of the file to be executed. The filename must include either an .EXE or .COM extension. A partial or full path may be included, but only the specified directory is searched for the file. If no directory or disk drive is specified, the current working directory on the active drive is the only directory searched.

cmdline must contain any command line arguments which are to be passed to pathname. The length of cmdline is limited to 127 bytes including the terminating NULL.

The environment at env must consist of ASCIIZ variable strings of the form:

"variable=value"

where variable is the name of the environment variable (i.e., "PATH"), and value is the value of that variable (i.e., "C:\;C:\DOS;"). The entire environment must be double NULL terminated (i.e., a final NULL is required in addition to the terminating NULL of the final variable string) as in this example:

char envstr[]="COMSPEC=D:\\COMMAND.COM\0PATH=D:;C:\\DOS;C:\\UTIL;\n\0TEST=2\0";
char env[256];
char far *envptr;
segaddr envseg;
...
envseg = _ptr_to_seg(env); /* paragraph align env buffer */
envptr = (void far *)((long)envseg<<16);/* create far pointer */
_fmem_cpy(envptr, envstr, sizeof(envstr));/* copy envstr to env buffer */
exec_proge("prog.exe", env); /* exec prog with custom env */
...

A NULL environment may be specified by placing two NULLs at env.

The following symbolic constants (defined in PROGCTL.H) identify the termination codes which may be returned in the high byte of the return value after the child program has been successfully executed:

TERM_NORMAL(0x0000) Normal termination
TERM_CBREAK(0x0100) Ctrl-break termination
TERM_CRITICAL(0x0200) Critical device error
TERM_TSR (0x0300) TSR termination (DOS function 0x31)

_exec_syse may be used to execute a program anywhere in a specified path without specifying a .EXE or .COM extension for the name of the program.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

WARNING! This function requires approximately 250 bytes of stack space.

C/C++ Example
	{
	   char progname[82];
	   char cmdln[82];
	   int termcode;
	   _put_str("Program name? ");
	   _get_str(progname,80);
	   _put_str("Command line? ");
	   _get_str(cmdln,80);
	   if(termcode = _exec_proge(progname,0,_get_rootenvseg())==-1);
	      _put_str("ERROR  .xxx (extension missing)\n\r"); 
	   termcode &= 0xFF00;    /* strip level code */
	   switch(termcode)
	   {
	      case TERM_NORMAL: _put_str("Normal termination\n\r");
	         break;
	      case TERM_CBREAK: _put_str("Ctrl-break termination\n\r");
	         break;
	      case TERM_CRITICAL:_put_str("Critical device error\n\r");
	         break;
	      case TERM_TSR: _put_str("TSR termination...\n\r"); break;
	      default: _put_str("Invalid term code.\n\r"); break;
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char progname[] = "PROGNAME.EXE";/* program to execute */
	   char cmdln[] = {0};/* no cmdln options */
	   char *str;
	   ...
	   get_rootenvseg();/* DX = root env segment */
	   pushss
	   pop es	 	/* ES=SS (segment of progname) */
	   lea di,progname/* DI = offset of program name */
	   lea si,cmdln/* SI = offset of cmdln */
	   exec_proge();	/* exec prog w/ specific env */
	    jc label_060/* go handle error condition */
	   cmp al,-1	/* missing extension? */
	    jnelabel_010/*   n: find/display term code */
	   str = "\n\rERROR: missing extension";
	   mov si,str	/* DS:SI -> str */
	   jmp label_050
	label_010:
	   cmp ah,TERM_NORMAL/* Normal termination? */
	    jnelabel_020/*  n: try next */  
	   str = "\n\rNORMAL termination";
	   mov si,str	/* SI = offset of str */
	   jmp short label_050
	label_020:
	   cmp ah,TERM_CBREAK/* Control Break termination? */
	    jnelabel_030/*   n: try next */
	   str = "\n\rCONTROL BREAK termination";
	   mov si,str	/* DS:SI -> str */
	   jmp short label_050/* continue */
	label_030:
	   cmp ah,TERM_CRITICAL /* CRITICAL termination? */
	    jnelabel_040/*   n: try next */
	   str = "\n\rCRITICAL termination";
	   mov si,str	/* DS:SI -> str */
	   jmp short label_050
	label_040:
	   cmp ah,TERM_TSR/* TSR termination? */
	    jnelabel_060/*   n: continue */
	   str = "\n\rTSR termination";
	label_050:
	   put_str();	/* display termination message */
	label_060:
	   ...
	}

Source file _PCEXPGE.ASM ASM equiv EXEC_PROGE
See also
_exec_prog, _exec_sys

_exec_sys


Descrip
Executes a DOS command, batch file, or program.

Syntax
#include <progctl.h>
int _exec_sys(char *cmdstr);

Returns
0 if the program was successfully executed.

-1 if an error occurred.
e_code error code

Notes
This function executes the DOS command, batch file, or program specified in cmdstr. This is done by passing cmdstr to the command processor specified by the COMSPEC environment variable (usually COMMAND.COM). An exact copy of the current program environment is passed to the command processor.

cmdstr MUST consist of "/c " followed by the DOS command or program name and any command line arguments. The DOS command or program name and command line arguments should appear exactly as they would if they were typed in at the DOS command prompt. The length of cmdstr is limited to 127 bytes including the terminating NULL.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

WARNING! This function requires approximately 270 bytes of stack space.

WARNING! This function uses the _psp global variable in all models except TINY. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly Library.

C/C++ Example
	{
	   if(_exec_sys("/c command.com") == -1)
	   /* remember to use "/c" */
	      _put_str("An error occurred.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char cmdstr[] = "/c command.com";
	   ...
	   lea si,cmdstr
	   exec_sys();
	    jnce_sys_100
	   ... handle error return ...
	e_sys_100:
	   ...
	}

Source file _PCEXSYS.ASM ASM equiv EXEC_SYS
See also
_exec_prog, _exec_sys, _exit

_exec_syse


Descrip
Executes a DOS command, batch file, or program using a specified environment.

Syntax
#include <progctl.h>
int _exec_syse(char *cmdstr, segaddr env);

Returns
0 if the program was successfully executed.

-1 if an error occurred.
e_code error code

Notes
This function executes the DOS command, batch file, or program specified in cmdstr. This is done by passing cmdstr to the command processor specified by the COMSPEC environment variable (usually COMMAND.COM). An exact copy of the environment at env is passed to the command processor.

cmdstr MUST consist of "/c " followed by the DOS command or program name and any command line arguments. The DOS command or program name and command line arguments should appear exactly as they would if they were typed in at the DOS command prompt. The length of cmdstr is limited to 127 bytes including the terminating NULL.

The environment at env must consist of ASCIIZ variable strings of the form:

"variable=value"

where variable is the name of the environment variable (i.e., "PATH"), and value is the value of that variable (i.e., "C:\;C:\DOS;"). The entire environment must be double NULL terminated (i.e., a final NULL is required in addition to the terminating NULL of the final variable string) as in the following example:

char envstr[]="PATH=D:;C:\\DOS;C:\\UTIL;\0";
char env[256];
char far *envptr;
segaddr envseg;
...
envseg = _ptr_to_seg(env); /* paragraph align env buffer */
envptr = (void far *)((long)envseg<<16);/* create far pointer */
_fmem_cpy(envptr, envstr, sizeof(envstr));/* copy envstr to env buffer */
exec_syse("/c dir", env);/* exec "cmdstr" with custom env */
...

A NULL environment may be specified by placing two NULLs at env.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

WARNING! This function requires approximately 270 bytes of stack space.

WARNING! This function uses the _psp global variable in all models except TINY. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   if(_exec_syse("/c command.com", _get_rootenvseg()) == -1)
	      /* remember to use "/c ..." */
	      _put_str("An error occurred.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char cmdstr[] = "/c command.com";
	   ...
	   get_rootenvseg();/* DX = env segment to use */
	   lea si,cmdstr/* DS:SI -> command string */
	   exec_syse();	/* execute DOS command */
	    jnce_syse_100/* if error quit */
	   ... handle an error return ...
	e_syse_100:
	   ...
	}

Source file _PCEXSYE.ASM ASM equiv EXEC_SYSE
See also
_exec_prog, _exec_sys, _exit

_exit_to_dos


Descrip
Temporarily passes control to the DOS command processor.

Syntax
#include <progctl.h>
int _exit_to_dos(segaddr env);

Returns
0 if the DOS command processor was successfully executed.

-1 if an error occurred.
e_code error code.

Notes
This function temporarily suspends program execution and passes control to the command processor specified by the COMSPEC environment variable (usually COMMAND.COM). An exact copy of the environment at env is passed to the command processor, or if env is zero, an exact copy of the current program environment is used. The command processor displays the command line prompt and waits for input.

Control returns to the current program when "EXIT" is typed at the DOS prompt.

The environment at env must consist of ASCIIZ variable strings of the form:

"variable=value"

where variable is the name of the environment variable (i.e., "PATH"), and value is the value of that variable (i.e., "C:\;C:\DOS;"). The entire environment must be double NULL terminated (i.e., a final NULL is required in addition to the terminating NULL of the final variable string) as in the following example:

char envstr[]="PATH=D:;C:\\DOS;C:\\UTIL;\0"\
" PROMPT=Type \"EXIT\" to Return to Program $g\0";
char env[256];
char far *envptr;
segaddr envseg;
...
envseg = _ptr_to_seg(env); /* paragraph align env buffer */
envptr = (void far *)((long)envseg<<16);/* create far pointer */
_fmem_cpy(envptr, envstr, sizeof(envstr));/* copy envstr to env buffer */
_exit_to_dos(env); /* exit to DOS w/custom prompt */
...

A NULL environment may be specified by placing two NULLs at env.

e_code may be obtained using the _get_ecode function. Symbolic constants for e_code values are defined in Appendix A.

WARNING! This function requires approximately 270 bytes of stack space.

WARNING! This function uses the _psp global variable in all models except TINY. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   segaddr envseg;
	   _put_str("\n\rEnter \"EXIT\" to return");
	   envseg = _get_envseg(_get_psp());/* use envseg for exit */
	   if(_exit_to_dos(envseg) == -1)
	      _put_str("Function was unsuccessful.");
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   ...
	   str = "\n\rEnter \"EXIT\" to return to program";
	   mov si,str	/* SI = offset of str */
	   put_str();	
	   get_psp();	/* get program segment prefix */
	   get_envseg();	/* get program's environment */
	   exit_to_dos();	/* shell to dos */
	    jnce_to_dos/* if error, display next msg */
	   str = "Function was unsuccessful.";
	   mov si,str
	   put_str();
	e_to_dos:
	   ...
	}

Source file _PCXTDOS.ASM ASM equiv EXIT_TO_DOS
See also
_exec_sys, _exec_sys

_get_curenvseg


Descrip
Returns the segment address of the current program's inherited environment.

Syntax
#include <progctl.h>
segaddr _get_curenvseg(void);

Returns
The segment address of current inherited environment.

Notes
This function returns the segment address of the current program's inherited environment. This environment may be manipulated by passing the returned segment address to any of the Spontaneous Assembly environment functions.

WARNING! This function uses the _psp global variable in all models except TINY. When using Spontaneous Assembly For C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   char far *varname;
	   _put_str("\n\rCurenvseg: \n\r");/* display msg */
	   varname = _get_env("PATH",_get_curenvseg());
	   if(varname == NULL)
	      _put_str("Current env \"PATH\" varname not found.");
	   else
	      _fput_str(varname);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   char varname[] = "PATH";
	   ...
	   str = "\n\rCurenvseg: \n\r";
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display msg */
	   get_curenvseg();/* get current env seg */
	   lea si,varname/* SI = offset of varname */
	   get_env();	/* is varname "PATH" found? */
	    jc label_100/*   n: jump to next label */
	   mov ax,es	/* ES:DI -> varname */
	   mov ds,ax
	   xchgdi,si	/* DS:SI -> varname */
	   jmp short label_200

	label_100:
	   str = "Current environment \"PATH\" varname not found.";
	   mov si,str	/* SI = offset of str */
	label_200:
	   put_str();	/* display string */
	   ...
	}

Source file _PCCURSG.ASM ASM equiv GET_CURENVSEG
See also
_get_dosenvseg, _get_env, _get_parenvseg, _get_rootenvseg

_get_dosenvseg


Descrip
Returns the segment address of the active DOS environment.

Syntax
#include <progctl.h>
segaddr _get_dosenvseg(void);

Returns
Segment address of the active DOS environment.

Notes
This function returns the segment address of the active DOS environment. This is the environment of the currently active COMMAND.COM. If no secondary copies of COMMAND.COM are present, this environment is also the root environment. This environment may be manipulated by passing the returned segment address to any of the Program Control environment functions.

WARNING! The _osmajor and _osminor global variables must be properly initialized before this function is called. When using Spontaneous Assembly For C/C++, these variables are supplied and initialized by the compiler instead of the Spontaneous Assembly library. The results are undefined if _osmajor and _osminor are not initialized.

WARNING! This function uses the _psp global variable in all models except TINY. When using Spontaneous Assembly for C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   char far *varname;
	   _put_str("\n\rDOSenvseg: \n\r");/* display msg */

	   varname = _get_env("PATH",_get_dosenvseg());
	   if(varname == NULL)
	      _put_str("DOS environment \"PATH\" varname not found.");
	   else
	      _fput_str(varname);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   char varname[] = "PATH";
	   ...
	str = "\n\rDOSenvseg: \n\r";
	mov si,str	 /* SI = offset of str */
	put_str();	 /* display msg */
	get_dosenvseg();/* get DOS env seg */
	lea si,varname/* SI = offset of varname */
	get_env();	 /* is varname "PATH" found? */
	 jc label_100/*   n: jump to next label */
	mov ax,es	 /* ES:DI -> varname */
	mov ds,ax
	xchgdi,si	 /* DS:SI -> varname */
	jmp short label_200

	label_100:
	str = "DOS environment \"PATH\" varname not found.";
	mov si,str	 /* SI = offset of str */
	label_200:
	put_str();	 /* display "str" or varname */
	...
	}

Source file _PCDOSSG.ASM ASM equiv GET_DOSENVSEG
See also
_get_curenvseg, _get_env, _get_parenvseg, _get_rootenvseg

_get_env


Descrip
Returns a pointer to the value of an environment variable.

Syntax
#include <progctl.h>
char far *_get_env(const char *varname, segaddr env);

Returns
A pointer to varname in the specified environment.

NULL if varname is not present in env.

Notes
This function searches the environment at env for the varname environment variable. If varname is found in env, a pointer to the value of varname (the portion of the environment variable string which follows the equals sign) is returned. NULL is returned if varname is not found. varname must NOT include an equal sign. The search for varname is case insensitive.

WARNING! The returned pointer should only be used to read the environment. _set_env should be used to write to the environment. Writing to an environment directly may corrupt the environment. The results are undefined if env is invalid.

C/C++ Example
	{
	   char far *varname;
	   segaddr env_seg;
	   _put_str("Program's environment path: \n\r");
	   env_seg = _get_envseg(_get_psp());
	   if((varname = _get_env("PATH",env_seg)) != 0)
	      _put_str("Unable to find environment varname \"PATH\".");
	   else
	   {
	      _fput_str(varname);
	      if((_set_env("PATH=New Path",env_seg)) != 0)
	         _put_str("Error setting new \"PATH\" in environment!");
	      else
	      {
	         _put_str("New \"PATH\" = ");
	         if((varname = _get_env("PATH",env_seg)) != 0)
	            exit(0);
	         else
	            _fput_str(varname);
	      }
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   ...
	   get_psp();	/* DX = _psp */
	   get_envseg();	/* get programs env segment */
	   str = "PATH";	
	   mov si,str	/* DS:SI -> str */
	   get_env();	/* PATH variable string found? */
	    jc label_010/*   n: quit */
	   str = "Program's current \"PATH\": ";
	   mov si,str	/* DS:SI -> str */
	   put_str();	/* display str */
	   mov ax,es
	   mov ds,ax
	   xchgsi,di	/* DS:SI -> PATH string */
	   put_str();	/* display PATH string */
	label_010:
	   ...
	}

Source file _PCGETEN.ASM ASM equiv GET_ENV
See also
_get_curenvseg, _set_env

_get_envseg


Descrip
Returns the segment address of any program's environment.

Syntax
#include <progctl.h>
segaddr _get_envseg(segaddr progpsp);

Returns
The segment address of the program environment associated with progpsp.

Notes
This function returns the segment address of the environment assigned to progpsp, which must be a valid Program Segment Prefix address. The environment may be manipulated by passing the returned segment address to any of the Spontaneous Assembly environment functions.

The correct address is returned under all versions of DOS through 6.0, even if progpsp is a primary or secondary copy of COMMAND.COM.

WARNING! The _osmajor and _osminor global variables must be properly initialized before this function is called. When using Spontaneous Assembly For C/C++, these variables are supplied and initialized by the compiler instead of the Spontaneous Assembly library.

If _osmajor and _osminor are not initialized, the results are undefined.

WARNING! The results are undefined if progpsp is invalid.

C/C++ Example
	{
	   char far *varname;
	   segaddr env_seg;
	   ...
	   _put_str("\n\rEnvseg: \"PATH\" :\n\r");
	   env_seg = _get_envseg(_get_psp());
	   if((varname = _get_env("PATH",env_seg)) == 0)
	      _put_str("Current environment \"PATH\" var not found.");
	   else
	      _fput_str(varname);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char varname[] = "PATH";
	   char *str;
	   ...
	   str = "\n\rEnvseg: \"PATH\" :\n\r";
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display str msg */
	   get_psp();	/* get _PSP */
	   get_envseg();	/* get program's environment */
	   lea si,varname/* SI = offset of varname */
	   get_env();	/* is varname "PATH" found? */
	    jc label_100/*   n: jump to next label */
	   mov ax,es	/* ES:DI -> varname */
	   mov ds,ax;	
	   xchgdi,si	/* DS:SI -> varname */
	   jmp short label_200

	label_100:
	   str = "Current environment \"PATH\" var not found.";
	   mov si,str	/* SI = offset of str */
	label_200:
	   put_str();	/* display str */
	   ...
	}

Source file _PCENVSG.ASM ASM equiv GET_ENVSEG
See also
_get_curenvseg, _get_dosenvseg, _get_parenvseg, _get_rootenvseg

_get_parenvseg


Descrip
Returns the segment address of the current program's parent environment.

Syntax
#include <progctl.h>
segaddr _get_parenvseg(void);

Returns
The segment address of the parent environment.

Notes
This function returns the segment address of the current program's parent environment (i.e., the environment of the program which executed the current program). This environment may be manipulated by passing the returned segment address to any of the Spontaneous Assembly environment functions.

WARNING! The _osmajor and _osminor global variables must be properly initialized before this function is called. When using Spontaneous Assembly For C/C++, these variables are supplied and initialized by the compiler instead of the Spontaneous Assembly library. The results are undefined if _osmajor and _osminor are not initialized.

WARNING! This function uses the _psp global variable in all models except TINY. When using Spontaneous Assembly For C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   char far *varname;
	   _put_str("\n\rParenvseg: \n\r");/* display msg */

	   varname = _get_env("PATH",_get_parenvseg());
	   if(varname == NULL)
	      _put_str("Parent env \"PATH\" varname not found.");
	   else
	      _fput_str(varname);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   char varname[] = "PATH";
	   ...
	   str = "\n\rParenvseg: \n\r";
	   mov si,str	/* DS:SI -> offset of str */
	   put_str();	/* display msg */
	   get_parenvseg();/* get Parent env seg */
	   lea si,varname/* DS:SI -> offset of varname */
	   get_env();	/* is varname "PATH" found? */
	    jc label_100/*   n: jump to next label */
	   mov ax,es	/* ES:DI -> varname */
	   mov ds,ax
	   xchgsi,di	/* DS:SI -> varname */
	   jmp short label_200
	label_100:
	str = "Parent environment \"PATH\" varname not found.";
	mov si,str	 /* DS:SI = offset of str */
	label_200:
	put_str();	 /* display str or varname */
	...
	}

Source file _PCPRSEG.ASM ASM equiv GET_PARENVSEG
See also
_get_curenvseg, _get_dosenvseg, _get_env, _get_rootenvseg

_get_psp


Descrip
Returns the segment address of the Program Segment Prefix.

Syntax
#include <progctl.h>
segaddr _get_psp(void);

Returns
The segment address of the current program's PSP.

Notes
This function returns the segment address of the current program's Program Segment Prefix. This value is identical to the value stored in the _psp global variable.

WARNING! This function uses the _psp global variable in all models except TINY. When using Spontaneous Assembly For C/C++, this variable is supplied and initialized by the compiler instead of the Spontaneous Assembly library.

C/C++ Example
	{
	   segaddr prog_prfx;
	   prog_prfx = _get_psp();
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   segaddr prog_prfx;
	   ...
	   get_psp();
	   mov prog_prfx,dx
	   ...
	}

Source file _PCGTPSP.ASM ASM equiv GET_PSP
See also
_psp, start

_get_rootenvseg


Descrip
Returns the segment address of the DOS root environment.

Syntax
#include <progctl.h>
segaddr _get_rootenvseg(void);

Returns
The segment address of the DOS root environment.

Notes
This function returns the segment address of the DOS root environment. This is the environment of the primary copy of COMMAND.COM (even if a secondary copy of COMMAND.COM is active). This environment may be manipulated by passing the returned segment address to any of the Program Control environment functions.

WARNING! The _osmajor and _osminor global variables must be properly initialized before this function is called. When using Spontaneous Assembly For C/C++, these variables are supplied and initialized by the compiler instead of the Spontaneous Assembly Library. The results are undefined if _osmajor and _osminor are not initialized.

C/C++ Example
	{
	   char far *varname;
	   ...
	   _put_str("\n\rRootenvseg: \n\r");/* display msg */
	   varname = _get_env("PATH",_get_rootenvseg());
	   if(varname == NULL)
	      _put_str("Root environment \"PATH\" varname not found.");
	   else
	      _fput_str(varname);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str;
	   char varname[] = "PATH";
	   ...
	   str = "\n\rRootenvseg: \n\r";
	   mov si,str	/* DS:SI -> str */
	   put_str();	/* display msg */
	   get_rootenvseg();/* get Root env seg */
	   lea si,varname/* DS:SI -> varname */
	   get_env();	/* is varname "PATH" found? */
	    jc label_100/*   n: jump to next label */
	   mov ax,es	/* ES:DI -> varname */
	   mov ds,ax
	   xchgsi,di	/* DS:SI -> varname */
	   jmp short label_200

	label_100:
	   str = "Root environment \"PATH\" varname not found.";
	   mov si,str	/* DS:SI -> str */
	label_200:
	   put_str();	/* display str or varname */
	   ...
	}

Source file _PCRTSEG.ASM ASM equiv GET_ROOTENVSEG
See also
_get_curenvseg, _get_dosenvseg, _get_env, _get_parenvseg

_reset_argtbls


Descrip
Resets the command line parser to use the default parsing tables.

Syntax
#include <progctl.h>
void _reset_argtbls(void);

Returns
None

Notes
This function reinstalls the default command line parsing tables. These tables emulate the command line parsing syntax supported by most DOS commands.

The default parsing tables are defined as follows:

Insignificant Separator Table " \t"; (Space, Tab)
Significant Separator Table",;+"; (Comma, Semicolon, Plus)
Switch Character Table"/"; (Forward Slash)

Parsing tables are always assumed to be in DGROUP. Custom tables must be defined as static arrays.

These tables control command line parsing as follows:

Insignificant Separator Table: Command line characters found in this table are skipped when they appear before or after an argument. They also terminate an argument. They are not copied into the buffer.

Significant Separator Table: Command line characters found in this table terminate an argument. They are never skipped and they are not copied into the buffer.

Switch Character Table: Command line characters found in this table mark the beginning of a new argument and end any previous argument. They are copied into the buffer as the first character of an argument.

When a command line character is processed, these tables are searched in the following order: Switch Character Table, Significant Separator Table, Insignificant Separator Table. The character is then compared against CR and NULL to check for the end of the command line.

Custom command line tables may be installed using set_argtbls. Unless custom parsing tables are installed, command line arguments are processed using the default tables.

C/C++ Example
	{
	   char *str;
	   char argbuf[20];
	   static char argtbl[4] = {44,59,43,45}; /* ,;+- */

	   _set_cmdln("\n\rfile1 file2-file3 , file4;");
	   _put_str("Number of command line args: "); 
	   args = _arg_count();
	   _put_str(_ui_to_dec(args, argbuf)); /* 3 arguments */
	   _set_argtbls(INHERIT_PTR,argtbl,INHERIT_PTR);
	   /* set custom arg table */
	   _put_str("\n\rNumber of command line args: ");
	   args = _arg_count();
	   _put_str(_ui_to_dec(args, argbuf)); /* 4 arguments */
	   _reset_argtbls(); /* reset to default arg tables */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   static char argtbl[4] = {44,59,43,45}; /* ,;+- */
	   char buf[20];
	   char *str;
	   ...
	   pushss
	   pop es	 	/* ES=SS (cmdln pntr on stack) */
	   str = "\n\rfile1 file2-file3 , file4;";
	   mov di,str	/* DI = offset of cmdln */
	   set_cmdln();	/* set command line */
	   str = "Number of command line args: ";
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display str */
	   arg_count();	
	   mov ax,cx	/* AX = number of arguments */
	   lea si,buf	/* SI = offset of buf */
	   i_to_dec();	/* num args -> "string" */
	   put_str();	/* display number of args */
	   mov ax,-1	/* AX = offset of insig table */
	   mov bx,offset argtbl
	   mov dx,-1	/* DX = offset of switch table */
	   set_argtbls();	/* set custom parsing table */
	   str = "Number of command line args: ";
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display str */
	   arg_count();
	   mov ax,cx	/* AX = number of arguments */
	   lea si,buf	/* SI = offset of buf */
	   i_to_dec();	/* num args -> "string" */
	   put_str();	/* display new count arguments */
	   reset_argtbls();/* reset to default arg tables */
	   ...
	}

Source file PCRSARTB.ASM ASM equiv RESET_ARGTBLS
See also
_arg_next, _set_argtbls

_reset_cmdln


Descrip
Resets the command line address to the default location.

Syntax
#include <progctl.h>
void _reset_cmdln(void);

Returns
None
Notes
This function causes the _arg_count, _arg_next, and _arg_nth functions to process command line arguments on the default program command line. This command line resides at offset 0x81 in the PSP.

This function is equivalent to moving FFFF:0081 into cmdln_start and moving 0x81 into cmdln_next. The new command line address takes effect immediately.

An arbitrary command line address may be specified by calling _set_cmdln or by modifying cmdln_start and cmdln_next directly.

C/C++ Example
	{
	   char argbuf[20];
	   int args;
	   ...
	   _set_cmdln("\n\rfile1 file2-file3 , file4;");
	   _put_str("Number of command line args: "); 
	   args = _arg_count();
	   _put_str(_i_to_dec(args, argbuf));
	   _arg_reset();/* reset to beginning of cmdln */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char buf = [20];
	   char str[] = "\n\rfile1 file2-file3 , file4;";
	   ...
	   pushss
	   pop es	 	/* ES=SS (cmdln pntr on stack) */
	   lea di,str	/* DI = offset of cmdln */
	   set_cmdln();	/* set custom cmdln */
	   str = "Number of command line args: ";
	   mov si,str	/* SI = offset of string */
	   put_str();	/* display message */
	   put_newline();	/* CR,LF */
	   arg_count();
	   mov ax,cx	/* AX = number of cmdln args */
	   lea si,buf	/* SI = offset buf */
	   i_to_dec();	/* num args -> "string" */
	   put_str();	/* display number of args */
	   arg_reset();	/* reset to beginning of cmdln */
	   ...
	}

Source file PCSMCDL.ASM ASM equiv RESET_CMDLN
See also
_arg_next, _arg_reset, cmdln_next, cmdln_start, _set_cmdln

_set_argtbls


Descrip
Installs custom parsing tables for use by the command line parser.

Syntax
#include <progctl.h>
void _set_argtbls(char near *isep_table, char near *ssep_table, char near *sw_table);

Returns
None

Notes
This function installs custom command line parsing tables. These tables define the command line parsing syntax used by the _arg_count, _arg_next, and _arg_nth functions to process command line arguments. If -1 is specified for a particular table address, then the currently installed table remains installed. The symbolic constant INHERIT_PTR (0xFFFF) is provided for this purpose. (INHERIT_PTR is defined in SA_DEF.H.) Parsing tables must reside in DGROUP (global or static non-far data).

Command line parsing tables are ASCIIZ strings which identify argument separators and switch characters. They are used to parse the command line as follows:

Insignificant Separator Table (isep_table): Command line characters found in this table are skipped when they appear before or after an argument. They also terminate an argument. They are not copied into the buffer.

Significant Separator Table (ssep_table): Command line characters found in this table terminate an argument. They are never skipped and they are not copied into the buffer.

Switch Character Table (sw_table): Command line characters found in this table mark the beginning of a new argument and end any previous argument. They are copied into the buffer as the first character of an argument.

When a command line character is processed, these tables are searched in the following order: Switch Character Table, Significant Separator Table, Insignificant Separator Table. The character is then compared against CR and NULL to check for the end of the command line. The meaning of the CR character may be changed by placing CR in one of the three parsing tables. If the first character in a table is a NULL, then that table is ignored.

Default parsing tables are used to process the command line unless custom tables are installed using this function. The default parsing tables emulate the command line parsing syntax supported by most DOS commands. The default parsing tables are defined as follows:

Insignificant Separator Table" \t" (Space, Tab)
Significant Separator Table",;+" (Comma, Semicolon, Plus)
Switch Character Table"/" (Forward Slash)

The default command line parsing tables may be reinstalled at any time using _reset_argtbls.

C/C++ Example
	{
	   char *str;
	   char argbuf[20];
	   int args;
	   static char argtbl[4] = {44,59,43,45}; /* ,;+- */
	   ...
	   _set_cmdln("\n\rfile1 file2-file3 , file4;");
	   _put_str("Number of command line args: "); 
	   args = _arg_count();
	   _put_str(_ui_to_dec(args, argbuf)); /* 3 arguments */
	   _set_argtbls(INHERIT_PTR, argtbl, INHERIT_PTR);
		/* use these characters as delimiters */
	   _put_str("\n\rNumber of command line args: ");
	   args = _arg_count();
	   _put_str(_ui_to_dec(args, argbuf)); /* 4 arguments */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char buf[20];
	   char *str;
	   static char argtbl[4] = {44,59,43,45}; /* ,;+- */
	   ...
	   str = "\n\rfile1 file2-file3 , file4;";
	   mov di,str	/* DI = offset of cmdln */
	   pushss
	   pop es	 	/* ES=SS (pntr on stack) */
	   set_cmdln();	/* set custom cmdln */
	   str = "Number of command line args: ";
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display str */
	   arg_count();
	   mov ax,cx	/* AX = number of arguments */
	   lea si,buf	/* SI = offset of buf */
	   i_to_dec();	/* arg count -> "string" */
	   put_str();	/* display number of args */
	   mov ax,-1	/* AX = offset of insig table */
	   mov bx,offset argtbl /* BX = offset of sig table */
	   mov dx,-1	/* DX = offset of switch table */
	   set_argtbls();	/* set custom parsing table */
	   str = "Number of command line args: ";
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display str */
	   arg_count();
	   mov ax,cx	/* AX = number of arguments */
	   lea si,buf	/* SI = offset of buf */
	   i_to_dec();	/* arg count -> "string" */
	   put_str();	/* display count of arguments */
	   ...
	}

Source file _PCSARTB.ASM ASM equiv SET_ARGTBLS
See also
_arg_next, _reset_argtbls

_set_cmdln


Descrip
Specifies the address of the command line.

Syntax
#include <progctl.h>
void _set_cmdln(char far *cmdln);

Returns
None

Notes
This function specifies the location of the command line which is to be processed using the _arg_count, _arg_next, and _arg_nth functions. This is equivalent to moving cmdln into cmdln_start and moving the offset portion of cmdln into cmdln_next. The specified command line address takes effect immediately.

The default program command line resides at offset 0x81 in the PSP. This is the command line which is parsed by the _arg_... functions unless another command line address is specified. The command line address may be reset to this location by calling _reset_cmdln.

C/C++ Example
	{
	   char argbuf[20];
	   int args;
	   ...
	   _set_cmdln("\n\rfile1 file2-file3 , file4;");
	   _put_str("Number of command line args: "); 
	   args = _arg_count();
	   _put_str(_i_to_dec(args, argbuf));
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char *str = "\n\rfile1 file2-file3 , file4;";
	   ...
	   mov di,str
	   pushss
	   pop es	 	/* ES=SS (cmdln pntr on stack) */
	   set_cmdln();	/* set custom command line */
	   ...
	}

Source file _PCSCMDL.ASM ASM equiv SET_CMDLN
See also
_arg_next, _arg_reset, cmdln_next, cmdln_start, _reset_cmdln

_set_env


Descrip
Sets the value of a variable string in an environment.

Syntax
#include <progctl.h>
int _set_env(char *varstr, segaddr env);

Returns
0 if value of varstr was successfully set in env.

-1 if function was unsuccessful

Notes
This function sets the value of a variable string in env. varstr must be an ASCIIZ string in the form "varname=value", where value may not include an equal sign ('='). If varname is not currently present in env, it is added. If varname is present, its value is changed. If varstr is NULL, varname is deleted from env. -1 is returned if there is no equal sign in varstr or if there is insufficient room in env to perform the change.

The search for varname is not case sensitive.

WARNING! The results are undefined if env is undefined.

C/C++ Example
	{
	   char far *varname;
	   segaddr env_seg;
	   ...
	   _put_str("Program's environment path: \n\r");
	   env_seg = _get_envseg(_get_psp());
	   if((varname = _get_env("PATH",env_seg)) == 0)
	      _put_str("Unable to find environment varname \"PATH\".");
	   else
	   {
	      _fput_str(varname);
	      if((_set_env("PATH=New Path",env_seg)) != 0)
	         _put_str("Error setting new \"PATH\" in environment!");
	      else
	      {
	         _put_str("New \"PATH\" = ");
	         if((varname = _get_env("PATH",env_seg)) != 0)
	            exit(0);
	         else
	            _fput_str(varname); /* display new varname */
	      }
	   }
	   ...
	}
	...

Inline Assembly Example
	#include <inline.h>
	{
	   char outstr[5];
	   char varstr[] = "PATH=New Path";
	   char *str;
	   ...
	   mov si,str	/* SI = offset of str */
	   put_str();	/* display msg */
	   get_psp();	/* DX = psp */
	   get_envseg();	/* get env seg */
	   lea si,varstr/* SI = offset of varstr */
	   set_env();
	    jc test1_100
	   mov ax,dx	/* AX = segment address */
	   lea si,outstr/* SI = offset of outstr */
	   ui_to_hex();	/* convert segment to "string" */
	   jmp short test1_200

	test1_100:
	   str = "Error in setting new \"PATH\"";
	   mov si,str
	test1_200:
	   put_str();	/* display segment or errmsg */
	   ...
	}

Source file _PCSETEN.ASM ASM equiv SET_ENV
See also
_get_curenvseg, _get_env