New Commands

Startup Order
Tcl Commands
FORTRAN Commands
C Commands
Parameter Files

Source: newcmd.tcl

proc newcmd {args} {

   parseparm [parmloc newcmd] $args

   if { $cmdargc != 0 } {
      txwrite " Wrong number of arguments: $cmdargv" 10
      error {}
   }
#
#  This is just an example where the command takes no arguments
#  command usage -> command parameter=value parameter=value argument
#  The arguments are stored in a Tcl list called cmdargv, 
#  and the number of arguments is stored in cmdargc
#
#  For example:
#   command parm1=parval1 parm2=parval2 arg1 arg2
#
#  txwrite "   numargs: $cmdargc" 10
#  txwrite "   first: [lindex $cmdargv 0]" 10
#  txwrite "   second: [lindex $cmdargv 1]" 10
#
#  Would print:
#   numargs: 2
#   first: arg1
#   second: arg2
#  
#
#  Retrieve parameters
#
#  Unlike FORTRAN and C routines, Tcl determines data types on
#  the fly, so there is no need for routines that retrieve
#  the parameter values. The parseparm proc creates a parval
#  array which contains the values for all parameters.
#
   set logpar $parval(logpar)
   set strpar $parval(strpar)
   set intpar $parval(intpar)
   set realpar $parval(realpar)
   set dblpar $parval(dblpar)
   set listpar $parval(listpar)
#
#  Command body
#

}

The file containing the Tcl proc should end in .tcl, and be located in $XANADU/image/ximage/tcl. Note: Tcl commands may also be defined outside of the XIMAGE installation in the user's ~/.ximage directory or the directory defined by the XIMAGE_HOME environmental variable.

3. Create a parameter file for the pfiles directory

See Parameter Files. Note: If a Tcl command resides in ~/.ximage or where XIMAGE_HOME specifies, the parameter files must be there as well.

FORTRAN Commands

c
c  New command comments
c
      elseif ( command.eq.'NEWCMD' ) then
         call newcmd(cmdid,status)

Source: newcmd.f

      subroutine newcmd(Cmdid,Status)
      implicit none
c
c  Comments here
c
c  I  cmdid        (i) Command id
c  O  status       (i) Error flag (0=OK)
c
      integer Cmdid, Status
c
c  Local variables
c
      logical logpar
      character*100 strpar
      integer intpar, listnum, listmax
      parameter(listmax = 100)
      real*4 realpar, listary(listmax)
      real*8 dblpar

      Status = 0
c
c Check number of arguments here
c
c  Note: wrongargs prints arguments which are unaccounted 
c        for and sets status to -1
c
      call numcarg(cmdid,argc,status)
      if ( argc.ne.0 ) wrongargs(cmdid, status)
c
c  This is just an example where the command takes no arguments
c  command usage -> command parameter=value parameter=value argument
c  A couple of options are available for retrieving arguments:
c
c  Returns next argument as string
c     call nextcarg(cmdid, argument, MAX_STRLEN, status)
c 
c  Returns concatenation of all remaining arguments
c     call catcarg(cmdid, therest, MAX_STRLEN, Status)
c   
c
c  Retrieve parameters
c
      CALL GPARL(Cmdid,'LOGPAR',logpar,status)
      CALL GPARS(Cmdid,'STRPAR',strpar,status)
      CALL GPARI(Cmdid,'INTPAR',intpar,status)
      CALL GPARR(Cmdid,'REALPAR',realpar,status)
      CALL GPARD(Cmdid,'DBLPAR',dblpar,status)
      CALL GPARLR(Cmdid,'LISTPAR',listary,listnum,listmax,status)
      if ( status.ne.0 ) return
c
c  Command body
c
      return
      end

4. Create a parameter file for the pfiles directory

See Parameter Files

C Commands

Source: newcmd.c

#include <stdlib.h>
#include <stdio.h>
#include <string.h>

#include "../include/xcommon.h"
#include "../include/xmtcl.h"
#include "../include/cmddef.h"

#define STRMAX 256
#define LISTMAX 100

/*
 * newcmd --
 * Command description
 */
int
newcmd(ClientData cdata,Tcl_Interp* interp,int objc, Tcl_Obj* CONST objv[] )
{
   int status;
   cmddef *curcmd;
   pardef *parlist;

   int logpar, intpar, listnum;
   char strpar[STRMAX];
   float realpar, listary[LISTMAX];
   double dblpar;

   curcmd = cdata;
   status = 0;

   if ( !CParseParm(interp, objc, objv, curcmd) ) {
      return TCL_ERROR;
   }
   parlist = curcmd->parlist;
/*
 * Check number of arguments here
 *
 *  cwrongargs prints arguments which are unaccounted for
 */
   if ( curcmd->cmdargc != 0 ) {
      cwrongargs(curcmd->cmdargs);
      return TCL_ERROR;
   }
/*
 *  This is just an example where the command takes no arguments
 *  command usage -> command parameter=value parameter=value argument
 *  The arguments are available as strings in the linked list, 
 *  curcmd->cmdargs.
 *
 *  Tcl provides routines for getting the proper type.  Take the
 *  following example, which assigns the three arguments to a
 *  double array.
 *
 *  See the online manual for Tcl for other object-based routines:
 *  http://dev.scriptics.com/man/
 *  (Use command "puts $tcl_patchLevel" in ximage to determine version)
 *
 *  int i;
 *  double dbl[3];
 *  Tcl_Obj *tmpObj;
 *  argdef *curarg;
 
 *  curarg = curcmd->cmdargs;
 *  i = 0;
 *  while ( curarg ) {
 *     tmpObj = Tcl_NewStringObj(curarg->name, -1);
 *     Tcl_GetDoubleFromObj(xm_interp, tmpObj, &dbl[i]);
 *     curarg = curarg->next;
 *     i++;
 *  }
 */

   cgparl(parlist, "LOGPAR", &logpar, &status);
   cgpars(parlist, "STRPAR", strpar, STRMAX, &status);
   cgpari(parlist, "INTPAR", &intpar, &status);
   cgparr(parlist, "REALPAR", &realpar, &status);
   cgpard(parlist, "DBLPAR", &dblpar, &status);
   cgparlr(parlist, "LISTPAR", listary, &listnum, LISTMAX, &status);

/*
 *  Command body
 */

   if ( status != 0 ) { return TCL_ERROR; }
   return TCL_OK;
}

See Parameter Files

Parameter Files

Source: newcmd.par

#
#  Parameters for newcmd
#
logpar,b,a,no,,,"Logical parameter[y/n]?"
strpar,s,a,,,,"String parameter"
intpar,i,a,,,,"Integer parameter"
realpar,r,a,,,,"Real parameter"
dblpar,r,a,,,,"Double parameter"
listpar,s,a,,,,"List parameter"
#mode,s,h,"h",,,""

Also, there is a special type which allows the retrieval of a list of real numbers delimited by spaces. In the parameter file, the string type is used, however, when GPARLR is called from FORTRAN, an array of reals is returned.

If you are familiar with parameter files, the default behavior of 'a' mode is 'h' or hidden mode. It is possible to make parameters behave similar to ftool arguments by giving them a 'q' mode. Each 'q' parameter will claim free arguments in the order that they appear in the parameter file. For example,

#
#  Parameters for othercmd
#
infile,s,q,,,,"Input file"
outfile,s,q,,,,"Output file"
mode,i,a,,,,"Mode"

othercmd mode=1 data.fits result.fits
othercmd mode=1 infile=data.fits outfile=result.fits