S A P / C H L O E SPECTRUM ANALYSIS PROGRAM APRIL 1986 F.Videbaek, Argonne National Laboratory. Physics Division 9700 S.Cass Avenue Argonne, Illinois 60439 U.S.A. S A P Page 1A 25 April 86 TABLE OF CONTENTS CONTENTS 1 INTRODUCTION. . . . . . . . . . . . . . . . . . . . 3 2 HOW TO GET STARTED. . . . . . . . . . . . . . . . . 3 3 SPECTRUM FILES. . . . . . . . . . . . . . . . . . . 3 3.1 Daphne Spectra . . . . . . . . . . . . . . . . . . 4 3.2 LISA Spectra . . . . . . . . . . . . . . . . . . . 4 3.3 Access By SPEAKEASY . . . . . . . . . . . . . . . 5 4 COMMAND SYNTAX. . . . . . . . . . . . . . . . . . . 5 5 COMMAND FILES. . . . . . . . . . . . . . . . . . . 5 6 LOGICAL COMMANDS . . . . . . . . . . . . . . . . . . 6 7 HELP FACILITY. . . . . . . . . . . . . . . . . . . 7 8 DOCUMENTAION OR LOG FILE. . . . . . . . . . . . . . 7 9 TITLES AND SUBTITLES. . . . . . . . . . . . . . . . 7 10 SPECTRUM REFERENCES. . . . . . . . . . . . . . . . . 8 11 NEWS. . . . . . . . . . . . . . . . . . . . . . . . 8 12 PROGRAM INTERRUPTION. . . . . . . . . . . . . . . . 9 13 TAPE HANDLING. . . . . . . . . . . . . . . . . . . . 9 14 COMMANDS NOT SETUP AT ANL. . . . . . . . . . . . . 10 15 DISPLAY DEVICES . . . . . . . . . . . . . . . . . 11 15.1 TEKTRONIX 4114 . . . . . . . . . . . . . . . . . 11 15.2 TEKTRONIX 4115 . . . . . . . . . . . . . . . . . 12 16 VT240 . . . . . . . . . . . . . . . . . . . . . . 12 17 IMPLEMENTATION. . . . . . . . . . . . . . . . . . 12 18 SUMMARY OF COMMANDS. . . . . . . . . . . . . . . . 14 19 COMMANDS . . . . . . . . . . . . . . . . . . . . . 16 19.1 Printing And Plotting. . . . . . . . . . . . . . 16 19.2 Tape Manipulation. . . . . . . . . . . . . . . . 21 19.3 Spectrum File Manipulation . . . . . . . . . . . 27 19.4 Spectrum Manipulation. . . . . . . . . . . . . . 32 19.5 Spectrum Display. . . . . . . . . . . . . . . . 68 19.6 Regions And Markers. . . . . . . . . . . . . . . 73 19.7 Control Commands . . . . . . . . . . . . . . . . 81 19.8 Commandfile Commands. . . . . . . . . . . . . . 92 S A P Page 2 25 April 86 NOTE This present manual is the users manual for the spectrum analysis program CHLOE/SAP. The present version of the manual is almost completed. The manual is still in the process of being updated and the present documentation reflects this. If you find problems in the manual please contact F.Videbaek. S A P Page 3 25 April 86 USERS MANUAL 1 INTRODUCTION. The Spectrum Analysis Program is a program to analyze one- and two-dimensional spectra on the VAX. The original Niels Bohr Institue version used a GRINNEL graphic system for the display of spectra. The present version was developed for the ANL Chemistry VAX 11/780 and has been modified to run on the Physics division VAX 11/780 and ATLAS VAX 11/750 Computers. As display devices the program can use TEKTRONIX 4114 display terminals , TEKTRONIX 4115B color display terminals or a more rudimentary display on TEK4010 compatible display terminals. Recently the tektronix 4107 and 4111 color terminal has been added as a possible devices. The spectra you want to analyze must reside on spectrum files created on the disc , or be DAPHNE spectra created in the current process. 2 HOW TO GET STARTED. A system wide logical name exists which points to the directory in which the executable elements, command files, and datafiles needed to execute SAP. This is sapdir: . To define the symbol execute the following DCL command. $@sapdir:sapassign Once this is done it should be possible to performe the operatrions described in this manual. 3 SPECTRUM FILES. Each user on the VAX should have his/her own spectrum file. Usually, one will have a default spectrum file with the name spectra. Actually each spectrum file consists of three files, one describing the content of a spectrum file, one containing the headers for all spectra and one with the spectra. For the default spectrum file a user will have the following 3 files. 1 - spectra.sph header file 2 - spectra.spc catalog file 3 - spectra.sps spectrum file When the program is started it connects to this default file. This means that users have access to spectra which are called s1,s2,.. etc. These may or may not be present. You can have access to several spectrum files at the same time. If you want to use this facility you must connect to such a file. This is done by giving the name of the file and giving S A P Page 4 SPECTRUM FILES. 25 April 86 a prefix by which you will reference the spectra e.g. by calling them t1,t2,... . Note that any given spectrum file can only be accessed by one user at a time You can specify if you only want to read from a spectrum file. This will be the default for spectrum files other than your own in order to prevent changes and deletions of spectra in other user's files. Spectrum files can be created be running the program $crspfile It will ask a series of questions which should be answered appropiately. Please see the example later. 3.1 Daphne Spectra If DAPHNE is running and you have a set of histograms created it is possible to look at thise spectra using SAP/CHLOE and performe spectrum manipulation. After the histograms are created execute the program to map to the spectra by $maptodap This will creat two set of spectrum files with the names 1 - dap1d.spc and dap1d.sph 2 - dap2d.spc and dap2d.sph which are the catalog and header files respectively. Note that the headers are created at this time which means that runnumbers and titles reflects the status at the time of the mapping. To access the spectra in SAP/CHLOE you have to connect to these spectrum files, (see later). 3.2 LISA Spectra LISA spectra are not directely accessible. A program exists however which can read a LISA spectrum dump file, and add all spectra or a selected set to a SAP/CHLOE spectrum file. This program can be executed by the command $lisatosap which will ask you some fairly trivial questions. NOTE: This command has not been tested carefully but works for a couple of LISA files generated by LISA version 100. It is likely it also works for lower versions numbers. S A P Page 5 SPECTRUM FILES. 25 April 86 3.3 Access By SPEAKEASY A set of SPEAKEASY linkules have been written by S.J.Sanders which can read from and write to one and two dimensional histograms. The two linkules are named sapget and keepsap. For more information contact S.J.Sanders. 4 COMMAND SYNTAX. Commands are typed on the terminal as one input line. A command consists of a main-command and one or more sub-commands. A main-command and sub-command each consists of a name followed by parameters separated by commas. Parameters are names, real numbers and integer numbers. Spectrum references are parameters, i.e. a name. The following is an example of a command display spec,s2 scale,12 display is the main-command spec,s2 is the first sub-command. scale,12 is the second sub-command. the sub-command spec has one parameter s2 which is a spectrum name. The sub-command scale has one parameter 12 which indicates the new scale to be used. 5 COMMAND FILES. Commands cannot only be read from the terminal but also from a command file. The command file consists of lines of text, each being a command as typed on the terminal. A command file is also called a command procedure. The default prefix of a command file is .com The control of the data stream is done by the following commands. call, Read from a file return Go back to reading from terminal. pause Suspend temporarily the reading from the command file. resume Resume the reading from the command file. S A P Page 6 COMMAND FILES. 25 April 86 terminate Terminate reading of the command file. When a command from a command file is executed and an error occurs, the analysis program issues a 'pause' command and the user can decide whether to 'resume' or 'terminate' reading from the command file. Command procedures can be called by another command procedure in up to 7 levels. When calls are nested, notice that the 'return' command transfers control to the previous level and 'terminate' to the terminal input level. Parameters can be transferred to the command procedure, i.e. the actual values are not determined until the time at which the 'call' command is executed. The precise format is call,,,,...,> The parameters ... can be integers, reals or names as parameters for a normal command line. To reference the parameter no. i within a command procedure, the command which uses the parameter should instead of the parameter have a form %i, i.e. percentage sign followed by a number. The following example illustrates the method. Command Procedure dplot.com display spec,%1 log,%2 color,3 plot integrate whole return It can e.g. be executed as follows. call,dplot.com,s17,5 . and later as . call,dplot.com,s35,5 With the first line the actual commands are display spec,s17 log,5 color,3 plot integrate whole return 6 LOGICAL COMMANDS It is possible to make shorthand notation for commands or part S A P Page 7 LOGICAL COMMANDS 25 April 86 of commands used often in SAP/CHLOE. These can be defined by the logical command. If a command line starts with an @ the letters up to the first delimiter ( , or ) are assumed to be a short hand notation. SAP/CHLOE looks in a table for the substitution to be made. In the default command file called when sap is started a couple of substitutions are defined. As an example take >logical define,d,"display spectrum" This can be used as >@d,s1 which is interpreted as >display spectrum,s1 7 HELP FACILITY. In order to get a quick description of commands a help facility has been introduced. The user can issue the command 'help' followed by the name of a command. This will cause the analysis program to type information on that command on the terminal. New commands are first described in the help facility before their description appears in this manual. 8 DOCUMENTAION OR LOG FILE. The analysis program creates a print file which contains a listing of commands issued , and output from the program . Exceptions from this rule is that the output from the print and list command for which a specific output device is given is not listed in the logfile, even when the output device is the terminal. At the end of a session the user is asked whether to keep, print or delete the file. If you keep the file the log of the following session is added to the existing file. The file will be printed on the line printer if the answer is print. You should make sure from time to time that the file is either printed or deleted to save free disc space. 9 TITLES AND SUBTITLES. All the spectra have a header block associated with them. The block contains the information on the size, the dimension and first and last channel etc. Each spectrum has also a name, S A P Page 8 TITLES AND SUBTITLES. 25 April 86 title and a subtitle. The title consists of up to 132 characters and the subtitle of up to 64 characters. The name will be up to 8 characters long. Spectra created from VAXEVA and DAPHNE will have a name as defined at definition time. When new spectra are created from existing ones the titles usually have to be modified. The program will output the current title and ask for the new title. If you answer by a the original title (subtitle) is kept. If you type a text the original title will be unchanged until the first non-blank character is met in the new title. This mean you can modify the end of a text by typing blanks (spaces) followed by the new text. 10 SPECTRUM REFERENCES. Spectra are called and referenced by their number in a given spectrum file. Since SAP/CHLOE can access several spectrum files a single letter is added to the reference name of a spectrum. A spectrum is referenced in a command by a single letter followed by the number ( e.g. s14) . The connection between the letter and a spectrum file is defined by means of the CONNECT command. As default SAP/CHLOE will initially try to connect a spectrum file with the name spectra. Many commands can access several spectra at once. Commands have quite often a subcommand spectra, . The spectrumlist is one of the possible constructions (Given as examples, not as stringent definitions.) 1: spectrum,s1,s2,t4,t1 the four spectra s1,s2,t4 and t1 2: spectrum,t5,to9 the spectra t5,t6,t7,t8,t9 3: spectrum,s all spectra with prefix s. 4: spectrum,next the spectrum with a number one higher that the currently selected spectrum. 11 NEWS. Important changes will be described as a short note in a file which can be read by the analysis program . The command to read the file is 'news' . The output will stop after every 20 line to ask if you want more of the news. The listing will start with the most recent news. S A P Page 9 PROGRAM INTERRUPTION. 25 April 86 12 PROGRAM INTERRUPTION. Usually it is not possible to interrupt the analysis program in a controlled way when a command is executing. It is possible by executing a (press the key 'CTRL' and 'Y' simultaneously) to interrupt the processing and return to the VMS control commands. Only a subset of DCL commands can be executed if you want to continue. To make use of this feature use $SPAWN which will create a subprocess in which DCL- command can be used unrestricted. To return to SAP/CHLOE logout from the subprocess and issue a $CONTINUE command. If this it not done SAP/CHLOE is aborted and the spectrum file structure may be disrupted. To proceed the processing type $CONT to continue the analysis without problems. If you do otherwise you may get unpredictable results . E.g. the spectrum files may be corrupted and cannot be read. To execute dcl commands in a controlled way a the command DCL exists which will spawn a subrpocess with either a given command or will start a dcl session in the subrprocess. To exit from that session used logout and the control will return to SAP. Since some commands produce a lot of output to the terminal or line printer these can be interrupted by executing a . The listing will then be stopped in a controlled manner and the analysis program will be ready to read the next command. Also display of 2 dimensional spectra can be interrupted by C. 13 TAPE HANDLING. The use of spectrum tapes is somewhat complicated due to the features of the VAX-VMS operating system. Due to the multiuser enviroment tape stations must be allocated to the user before access, further tapes must be logicaly mounted before they can be used by the program. This can be accomplied in two different ways. 1) by the mean of the VMS-DCL commands $ALLOCATE and $MOUNT/FOREIGN. In this case a tape station cannot be used by other users before it is released by the DCL commands $DISMOUNT and $DEALLOCATE. These cannot be issued inside the sap program, so you have toexit from SAP/CHLOE to release a tape station. 2) by the mean of the SAP/CHLOE commands reserve and mount. In this case the tape station is reserved until the SAP/CHLOE commands demount and release are given, or until SAP/CHLOE exists. This is the ideal way to proceed if you only want to allocate the tapes during short periods. S A P Page 10 TAPE HANDLING. 25 April 86 The analysis program uses tape to write spectra onto , and to read spectra from. The tape from which spectra are read is called the input tape and is referenced by 'tpin' and an output tape to which spectra will be written is referenced by 'tpout'. In order for SAP/CHLOE to know onto what tape drive the tpin or tpout tape is mounted the protect command should be used. One of the subcommand specifies a . On an tape from which you want to read this will be the highest file number from which SAP/CHLOE will allow reading. During positioning for a given file it is checked that an logical end-of-tape ( double EOF mark) is not met. On output the program will search for a logical end-of-tape at which position the write command will start the writing of spectra. If a the is specified as 0 no search is made, and writing will start from the beginning of the tape. The same physical tape can be used for input and output. Tape devices are specified by internal names of mt0 and mt1. These refer to MTA0 and MFA0 on the PHYA , and MFA0 and MFA1 on the ATLA VAX. The names are defined by common command file called when SAP/CHLOE is started by means of the commands 'set tapedevice..' . If you purposly want to overwrite existing spectra you must use the command 'inittape file,' which will write a double eof at the given file, becoming the new first free file. This must also be done if you want to write on a tape which has no double eof (e.g. the tape is created on RC4000). If the first free file is specified as 0, meaning an empty tape, no search for double eof is made, so you do not need to do a 'inittape' command for an empty tape. 14 COMMANDS NOT SETUP AT ANL. The original version of SAP/CHLOE contained several usefull commands e.g. for plotting of spectra. This commands have now been implemented so plots of 1d and 2d contour plots can be produced on the LASER printer/plotter. To get a fast plot of spectra you can use the hardcopy command when spectra are displayed on the TEKTRONIX 4114 display. S A P Page 11 DISPLAY DEVICES 25 April 86 15 DISPLAY DEVICES Several terminal types can be used by the SAP program. The terminal port and the type of the terminal are defined by logical names. The terminal port is defined by "TEKTRONIX". The terminal type is defined by "TEKTRONIX_MODEL". The terminal port logical name should always be defined beforehand. The terminal type will be requested if not given as a logical name when entering a display session. Due to the installation of the PHYLIS switch assignement of the graphics terminals cannot be done by device channels on the 780 The terminal to be used for graphics should still be defined by the logical name TEKTRONIX. To use a terminal make sure it is connected to PHYA.When connected it responds by giving a terminal line like 5t8. To use that terminal as a ghraphics terminal for SAP running from a different command terminal the name of the line should be assigned to tektronix. The kind of the terminal should be defined by the logical name TEKTRONIXMODEL. e.g $define tektronix 5t8 $define tektronixmodel tk4115 If SAP is to use the terminal itself as a graphics terminal e.g. when working with a vt240 or tk4111 do the following assignements $define tektronix tt $define tektronixmodel vt240 The terminal types presently defined are "TK4010" , "TK4114", "TK4115", "TK4107" , "TK4111" "TK4208" , "HIREZ" and "VT240". 15.1 TEKTRONIX 4114 To use the Tektronix 4114 properly it is necessary during cursor input not to use the = RETURN as a terminator for the input command. Use preferably the SPACE to terminate, future commands may use special keys. The i/o is done to the device with the logical name TEKTRONIX. Colors for line drawing are simulated by using different patterns. Colors for 2d intensities are made using symbols. S A P Page 12 DISPLAY DEVICES 25 April 86 15.2 TEKTRONIX 4115 To use the Tektronix 4114 properly it is necessary during cursor input not to use the = RETURN as a terminator for the input command. Use preferably the SPACE to terminate, future commands may use special keys. The i/o is done to the device with the logical name TEKTRONIX. The program can take input from the 4115B display terminal itself or from an adjacent terminal. When the terminal itself is used for input from the dialog area following assignement must be made If the tektronix 4115 is equiped with the DMA interface as on the ATLAS VAX 11/750 the logical name "DMA4110" defines the DMA channel. Please note that once SAP/CHLOE is started this way it does not take advantage of the type ahead feature of command input (In order not to disturb the graphics information being passed to the terminal). The Tektronix 4115B in the ATLAS dataroom has a DMA interface. This can be enabled by the following logical assigment $ assign XTA0: DMA4110 16 VT240 A VT240 terminal can be used as the display .It will be setup in tektronix mode. The terminal graphics menu should be setup such that the GIN terminator is CR. The display quality is inferior to that of a 4114 or 4115 , in particular the text will have to large reletive sizes, and the command input will be echoed at random places on the screen The i/o is done to the device with the logical name TEKTRONIX. Please note that once SAP/CHLOE is started this way you can not make use of the type ahead feature of the terminal (In order not to disturb the graphics information being passed to the terminal). 17 IMPLEMENTATION. To be able to use SAP/CHLOE and the commonly used symbols S A P Page 13 IMPLEMENTATION. 25 April 86 mentioned in this manual you should in your login command file include the following call $@sys$sysdevice:[daphne.sap]sapassign S A P Page 14 SUMMARY OF COMMANDS. 25 April 86 18 SUMMARY OF COMMANDS. COMMAND Printing and plotting of data: HARDCOPY PRINT PRPLOT CPLOT Tape manipulation: DEMOUNT INITTAPE MOUNT PROTECT READTAPE RELEASE RESERVE REWIND UNLOAD WRITE Spectrum file manipulation: CONNECT COPY DECONNECT LIST PACK TRUNCATE RESEQUENCE Spectrum manipulation: ARITMETIC BACKGROUND CHOP COMPRESS COMPARE CREATE DELETE DECAY EXTRACT ENERGY FUNCTION GAUSS INTEGRATE INVERT LIST MODIFY PRINT PROJECT SELECT TITLE TRANSFORM T2TRANSFORM ZERO S A P Page 15 SUMMARY OF COMMANDS. 25 April 86 Spectrum display: DISPLAY COLOR COMPARE CLEAR Regions and markers: CRMARSET DAM (Delete All Marker) DMAR (Delete Marker) HIGH LIST LOW MMAR (Move Marker) NMAR (New Marker) REGION RESTORE SAVE SELECT SMAR (Select Marker) WINDOW General commands for control: BELL DATE DCL DUMP EXIT GRAPHICS HELP LOGICAL NEWS PURGE REPORT SET SHOW SPOOL WAIT Command file: CALL RETURN REPEAT PAUSE TERMINATE RESUME S A P Page 16 COMMANDS 25 April 86 19 COMMANDS The following chapter gives a more detailed description of the commands available in the SAP/CHLOE program. Each command is described first by a short introduction followed by descriptions of all the subcommands for a given command. 19.1 Printing And Plotting. Plotting facilities in SAP/CHLOE are limited (at ANL) but hardcopies of the displays can be made on the tektronix hardcopiers. Plotting of 1d spectra can now be made to plotfiles which can be spooled to the Versatec printer/plotter. HARDCOPY Execute the hardcopy function for a tektronix 4114 or 4115. It is essential to use this command for the 4114 since part of the display is kept in refresh segments which will result in a random blur on the copy if only the hardcopy buttom is used. The command will change all refresh segments to be stored before executing the hardcopy command. A textstring can be given as a parameter to the command, and will be displayed above the spectrum. format: hardcopy hardcopy, e.g. hardcopy,"58Ni + 208Pb - 550MeV" PRINT Print the channel by channel content of the spectra specified as subcommands. The part of the spectrum which can be printed can be either the whole spectrum , the window region, or a region defined by the 'channels' subcommand. The output can be routed to the lineprinter, the terminal, or to a discfile. format: print spectrum, ... on Defines the output medium. You can specify 'printer' , 'terminal' or the name of a discfile. S A P Page 17 COMMANDS 25 April 86 e.g. print spectrum,s1 on,printer or print spec,s3 on,savedprint.dat A printfile can later be physically printed by means of the 'spool' command. spectrum Defines the spectra to be printed. Either specify a list of up to 20 spectra, or specify a range of spectra. e.g. print spectrum,s1,t2,t3 or print spectrum,s3,to5 bin Sum channels into bins before printing. The size of the bins are defined by the parameters to the subcommand. The binning factor can only be an integer value. format: print bin, ... for 1d print bin,, ... for 2d e.g. print bin,2 spectrum,s1 whole This subcommand specifies that all channels of a spectrum is to be printed. No additional parameters are given. window The region defined by the window is printed. This requires that the spectrum is or has been recently displayed. If no window exists the whole spectrum is printed. channels Define the region to be printed . The channel numbers are given as additional parameters. format: print [...] channels,, print [...] channels,,,, You can omit and if the spectrum is one dimensional. You can further omit . In this case will be set to the last channel of the spectrum. e.g. print spec,s4 channels,300,670 on,printer format S A P Page 18 COMMANDS 25 April 86 Determine the format of the output listing. The format can be choosen to be convenient for reading by other programs like figure. format: print format,print default format channels with zeroes are suppressed print format,figure all channels are printed. No channel numbers. The print is preceeded by 3 lines text, 1 line with number of channels 1 line with first channel followe by a one. Note this is mainly usefull for 1d spectra. PRPLOT Print the 2d-spectra specified as subcommands in a 2 dimensional layout. Either the content can be represented by it's value or it can be represented by a single character to obatine a density like printout. The whole spectrum , the window region or a window defined by the 'channel' subcommand will be printed. You can route the output to the lineprinter or to a discfile. format: prplot spectrum, ... on Defines the output medium. You can specify 'printer' , 'terminal' or the name of a discfile. e.g. prplot spec,s1 on,printer or prplot spec,s3 on,savedprint.dat A printfile can later be physically printed by means of the 'spool' command. spectrum Defines the spectra to be print-plotted. Either specify a list of up to 20 spectra, or specify a range of spectra. e.g. prplot spec,s1,t2,t3 or prplot spec,s3,to5 bin Sum channels into bins before printing. The binning can only be done in integer values. format: prplot bin, ... for 1d prplot bin,, ... for 2d S A P Page 19 COMMANDS 25 April 86 whole This subcommand specifies that all channels of a spectrum are to be printed. No additional parameters are needed. window The region defined by the window is printed. This requires that the spectrum is or have recently been displayed. If no window exists the whole spectrum is printed. channels Define the region to be printed . The channel numbers are given as additional parameters. format: prplot [...] channels,, prplot [...] channels,,,, You can omit and if the spectrum is one dimensional. You can further omit . In this case will be set to the last channel of the spectrum. e.g. prplot spec,s4 channels,300,670 on,printer format If this subcommand is given then the bin content is print - plotted. This means that the output will not be as compact. cut Define the lowest value of a bin which will be output. The content of a bin minus the cut value is the basis for print - plotting. format: prplot [...] cut, CPLOT Produce a plot of a one dimensional spectrum. The plot can be routed to either the laser printer/plotter or to the Versatec printer/plotter. The layout of the plot is NOT given by the layout on the screen but by the means of parameters given to the command. If spectrum is not specified then the current spectrum ( if any) is plotted. The scale i.e. maximum content is either calculated from maximum content in the selected part of the spectrum or from the value given in the 'max' subcommand. A spectrum is output to only one page of the versatec. The actual output is on a plotfile which can be spooled to the laserprinter S A P Page 20 COMMANDS 25 April 86 or the Versatec outside the SAP/CHLOE program. The name of the plotfile is by default SAPPLOT.QMS if it is a plot to the laser printer/plotter or SAPPLOT.VERPLT if it is to be routed to the versatec. spectrum Give the spectrum reference for the spectrum to plot. It must be one dimensional. format: cplot spectrum, [...] log The spectrum will be plotted using a logaritmic scale. chprmm Input the number of channels pr mm. This a a scale value only. The plot area is assumed to correspond to 100 cm * 24 cm. The physical size of cause will be only 8.5*11 inches. If chprmm is not given default values are choosen. The default value will try to fill the paper as well as possible. format: cplot chprmm, .The value can be a real number channels Define a window /region of the spectrum to be plotted. format: cplot channels,,x1> [...] max Define the channel content for the highest point to be on the display. If not specified - the maximum value of the spectrum is found. format: cplot max, [...] e.g. cplot max,500 fit If a fit have been defined i.e. gaussfit, exponential fit or a background has been defined on a displayed spectrum, it will be plotted together with the spectrum with a dotted curve if this subcommand is given to the cplot command. S A P Page 21 COMMANDS 25 April 86 format: cplot fit [...] energy The axis tic marks will be made a given energy values when an energycalibration exists. The parameter given to the subcommand is the distance between tic marks in units of the energy . format: cplot energy, [...] C2PLOT Plot a 2 dimensional spectrum as contour plot on a METAFILE which can be send to the LASER printer. The spectrum to be plotted must presently be displayed. scale Define the number of inches pr bin in the x-direction and y-direction. If not given SAP/CHLOE will make the largest possible picture on the plotting page. format: c2plot scale,, e.g. c2plot scale,2,1 bin Define the binning factor of the spectrum before t is plotted. The default is no binning i.e. 1,1 format: c2plot bin,, [...] cuts Define at what levels the contours are plotted. You can specify up to 7 different cuts. If this subcommand is not given SAP/CHLOE will ask for input of noofcuts and the cutvalues. 19.2 Tape Manipulation. Tapes are used for permanent spectrum storage. Spectra can be read from tape and to tape. The tape format is internal to SAP/CHLOE. Spectra written in other formats like e.g. SNAP can be converted to the SAP/CHLOE format by using a program convert. S A P Page 22 COMMANDS 25 April 86 (Ask F.Videbaek for more information). DEMOUNT Dismount logically a magnetic tape. The tape must have been mounted previously. format: demount,mt0 or demount,mt1 You can specify nounload as a subcommand. The tape is not unloaded when dismounted. INITTAPE Write a double end-of-file mark on the tape defined as the output tape. You must also specify the filenumber where the eof's should be written. The file number is the first free file of the tape. Files up to (filenumber -1) are saved. format: inittape file, tpout If only the output tape is defined then the subcommand tpout can be omitted. e.g. inittape file,234 MOUNT Mount logically a magnetic tape on the specified station. The tape must be physically mounted, and the tapestation reserved by the RESERVE command. format: mount,mt0 or mount,mt1 PROTECT Define the physical units used for the input tape , and for an output tape if requested. In addition to the name the first free file must be given. The file preceeding the first free file is the last ones which is logically accesible to the program when reading. When writing on an output tape this is the first file at which spectra will be written. If the program encounters an double e.o.f. before the first free file on output an error message and the current command is aborted. If an double e.o.f. is not a the requested position the tape will S A P Page 23 COMMANDS 25 April 86 scan forward until it does actually meet a double e.o.f. and start dumping from that position. Possible structures of this command are protect tpin, file, protect tpout, file, The former command defines the input tape. The later command defines an output tape to which spectra can be dumped directely. Tape units are designated mt0 and mt1. READTAPE Read spectra from a magnetic tape and store them on a spectrum area. Specify the files to be read and the format of the spectra on tape. If the file numbers are not specified the program asks for them. e.g. > read files,3,4 format,compact to,s The tape must be defined by the 'protect command' files Specify the files to be read given as 'first file' , 'lastfile' and ' file increment' . If the increment parameter is omitted 1 (one) is assumed. If the last file is not given only one file is read. format: readtape files,{,{,}} e.g. readtape files,4 ! read file 4 readtape files,4,8,2 ! read file 4,6 and 8 format The format of the spectra on the tape. possible formats are vax : Standard NBI/VAX spectrum format is written by the 'write spec,... ' command. This is the default format currently. to Defines the spectrum file to which the spectra are transferred by giving the prefix of the spectra. The default value is given by the value default prefix, initially 's' but can be changed by 'set prefix'. This means that the spectra will be saved on the default spectrum file 'spectra'. S A P Page 24 COMMANDS 25 April 86 e.g. > readtape file,3,14 to,t format,compact S A P Page 25 COMMANDS 25 April 86 RELEASE Release a previously reserved tape station format: release,mt0 or release,mt1 RESERVE Reserve a magnetic tape station. You can then use the mount command inside the sap program. Note that it is not needed to use the $ALLOCATE and $MOUNT/FOREIGN commands. format: reserve,mt0 or reserve,mt1 REWIND Rewind a tape which is protected. If only one tape is defined it is rewound, otherwise you must specify whether it is the input (tpin) or output (tpout) tape which should be rewound. UNLOAD Unload a tape which is protected. If only one tape is defined that is unloaded, other wise you must specify whether it is the input (tpin) or output (tpout) tape which should be unloaded. S A P Page 26 COMMANDS 25 April 86 WRITE Write a set of spectra to magnetic tape. The spectra can be written in either the internal VAX format. The spectra will be written to the tape protected as tpout. Note that this tape as for reading must be mounted foreign before you enter the spectrum analysis program. Each spectrum will be written as one file on the tape starting at ' first free file'. The spectra will be written in the internal format. format: write [spectrumlist] [format] e.g. write spectr,s10,to30 spectrum Defines the list of spectra to be written. As in many other commands you can specify a list of up to 20 spectra, a range of spectra or all spectra with a given prefix. format: write spectrum,,.., The spectra ... are written to tape. write spectrum,,to The spectra ,... are written to tape. write spectrum, All spectra with the prefix are written to tape. format Defines the format on the tape. The format can be the internal spectrum format or RC4000 compact format. The default is VAX format. format: write format,vax [spectrumlist] ! Write in VAX NBI-format. write format,compact ! Write in compact format. S A P Page 27 COMMANDS 25 April 86 19.3 Spectrum File Manipulation Spectrum files can be accessed by several commands. They are used for defining what spectrum files to use, listing of their content, packing and redefining the spectrum numbers. CONNECT Connect a spectrum file to the program. This is done by giving the name of the spectrum file ( spectrum files are realy 3 files so the name given is the part preceeding the prefix e.g. spectra or gamma). A prefix which is a single letter is logically assigned to the file and is used in references in commands. If you want to write to the spectrum file you must give the subcommand write. This should be done if you want to create new spectra on the file or delete existing spectra The program will attempt during initialization to connect to the spectrum file spectra and with the prefix s . connect file, prefix, write COPY Copy one or more spectra to a given spectrum file. You should specify a spectrum list. If no output file is given the default file is used. format: copy spectrum, [to,] spectrum The list of spectra list to copy. It can be of the form spectrum,,,..., ( the spectra listed will be copied) , spectrum,,to (the spectra ,,... will be copied) or spectrum, (all spectra with the prefix will be copied). e.g. copy spec,j3,j4 ( j3 and j4 will be copied to s.. and s.. ) to Defines the file to which the spectra are copied. The prefix is given as a parameter. format: copy [speclist] to,. S A P Page 28 COMMANDS 25 April 86 DECONNECT Deconnect a file previously connected to the program. The file can be referenced by the prefix or by it's actual name. In order for other users to use a file it must be deconected. Only one user have access to a spectrum file at any one time. format: deconnect file, deconnect pre, example: deconnect pre,s deconnect file,[replay.gamma]gamma NOTE ! Wildcard charecters are not allowed in the names LIST List the header information of the spectra specified. The listing can be on the terminal, on a printfile or on a user specified data file. You should specify some spectra to be listed. The list command can also be used to list the content of a marker set. format: list [subcommands] spectrum The subcommands specifies what spectrum headers are printed. format: spectrum,,,..., Spectra , .. are listed. spectrum,,to All spectra from to are listed. spectrum, All spectra with the prefix are listed. e.g. list spec,s2,s4,t67 list spec,s long The subcommands specifies that the full title of a spectrum headers are printed. format: long S A P Page 29 COMMANDS 25 April 86 e.g. list spec,s2,s4,t67 list spec,s long If the request is made to print on the printer or on a file the default to print in the long format. on Specify the output device. The header listing will appear on the terminal as a default. To route it to a print file use the subcommand on,printer . format: on,terminal ! list on the terminal on,printer list on a print file which will be routed by a 'purge' command or on exit from the program. on,name the listing will be saved on a new file with the name 'name.dat'. e.g. list spec,s10,to15 on,printer set Define the marker set to be listed. The set is given as the number. format: list set, [options] The options are otherwise as for list spectra. file List the headers of spectra from a spectrum tape written in VAX format. The tape to be listed is by default the input tape. format: list file,(,) [... If only is given only one header is listed. tpout The tape from which the headers is read ( when file is specifed) is taken to be the outputtape. PACK Pack a spectrum file. The allocation of the spectra will be moved to form a contigious area from the start of the file. The size of the file is not changed . This should be done by the truncate command or will be done at exit from SAP/CHLOE. S A P Page 30 COMMANDS 25 April 86 NOTE !!! Do not interrupt this command by Y . The command takes a while when the spectrum file is large. If no subcommand is given the file with the default prefix will be packed. prefix Define the file to be packed by mean of a prefix. pack prefix, file Define the file to be packed by means of a filename. pack file, TRUNCATE Unused blocks at the end of spectrum file is released. This command can be issued without a previous pack. It can be used whenever many spectra have been deleted. Note though that it will be implicitely issued at exit time for all spectrum files allocated. The header file is truncated as well. The file to be truncated is the default file unless otherwise specified. This command is executed implicitely when you exit from SAP/CHLOE. prefix Define the file to be truncated by the mean of a prefix. e.g. truncate prefix,t ! truncate the file connected with the ! prefix t file Define the file to be truncate by the mean of the filename. e.g. truncate file,spectra S A P Page 31 COMMANDS 25 April 86 RESEQUENCE Change the numbering of a list of spectra to be a consequtive list of numbers. The first number to be used for the new list is specified. Note that it is not always be possible to resequence a list of spectra since the command will never move a spectrum into an existing entry. During the resequencing process entries will be deleted as soon as a spectrum has been resequenced. Note also that when resequencing to a larger spectrum numbers the first may not always be the one you requested. In this case repeat the command. You must specify a spectrumlist i.e. a single spectrum, a sequence or a whole spectrum file format : reseq spectrum, [new,] spectrum Define what spectra to be given new numbers by the mean of a spectrum list format: spectrum, examples: spectrum, i.e. only one spectrum. spectrum,,to<2> i.e. the spectra from to are resequenced. new Specify the starting number of the new spectrum numbers. new, log A list of the old and nem spectrum numbers are printed. this is the default. nolog No information on new and old numbers are listed. NOT RECOMMENDED. S A P Page 32 COMMANDS 25 April 86 19.4 Spectrum Manipulation. Spectra can be manipulated in various ways. In this section the commands which can create or modify existing spectra by manipulating the spectra are described. ARITMETIC Performe aritmetic operations on spectra. The subcommands are still being developed and some operations can be performed on one dimensional spectra only. An aritmetric command as input require at least one spectrum and an operation to performe. Commands which only require one spectrum as input then usually request one parameter. format: arit ,[,spec or param] [subcommands] It is possible to add, subtract, multiply, divide, compress, smooth and shift spectra. Spectra must have the same dimension, but not necessarely the same size. The resulting spectrum will then have a size corresponding to the overlap region. A spectrum can also be multiplyed or divided by the function given by the latest 'function define' command. The resulting spectrum will either be a new spectrum, or be replacing an existing spectrum. add Add a spectrum to either a spectrum or a constant. format: arit add,, ! Add spectrum and . arit add,,! Add constant to all channels of . sub Subtract either a spectrum or a constant from a spectrum . format: arit sub,, Subtract spectrum from . arit sub,, Subtract constant from all channels of . mul Multiply either two spectra or one spectrum by a constant. format: arit mul,, Multiply spectrum and . arit mul,, Multiply all channels of by S A P Page 33 COMMANDS 25 April 86 div Divide two spectra or divide one spectrum by a constant. If the divisor in a channel is zero the divisor is set to one. format: arit div,, ! Divide spectrum by . arit div,, ! Divide spectrum by . fmul Multiply the spectrum with the function. If a function is not defined it is multiplyed by 1.0 . format: arit fmul, [...] Multiply spectrum by the function defined fdiv Divide the spectrum with the function. format: arit fdiv, [...] ! Divide the spectrum by the function. sqrt Generate a spectrum in which the content is the square root of the original channel content . format: arit sqrt, compress Compress a spectrum by a factor . This does only apply to one dimensitonal spectra. The factor must be larger than 1.0 . format: arit compress,, Compress can also be used for two dimensional spectra. In this case the command is arit compress,,, [...] Here the factors and must be integers. If they are given as real numbers the nearest integer is taken for each. S A P Page 34 COMMANDS 25 April 86 shift A one dimensional spectrum is shifted by number of channels to the right or to the left. A positive value indicates a shift to the right. The shift must be an integer number of channels. The shifting of a 2d spectrum is done by changing the header channel limits. If a new spectrum is specified for a 2d the content is actually moved. format: arit shift,,[,] [...] smooth A one dimensional spectrum is smoothed by a three point smooth. format: arit smooth, [...] A twodimensional spectrum is smoothed by a five point smooth using for each point (x,y) the content of (x-1,y) (x+1, y) (x,y-1) and (x,y+1) . format: arit smooth, [...] NOTE: please make sure that if you specify save, that the spectra have the same size. save Specify that the resulting spectrum is to be saved on a specific spectrum or a spectrumfile. You can specfy a spectrum to be saved in one of the spectra for which the operation is applied. format: arit [...] save, Save the resulting spectrum in arit [...] save, Save the resulting spectrum in a new spectrum on the spectrum file associated with the prefix . By default the command try to save spectra on the spectrum file with the default prefix . e.g. arit add,s1,s34 save,s34 bytes Specify the number of bytes pr channel used when a new 2d spectrum is generated as the result of the aritmetic operation. The spectrum can not hold the resulting spectrum if bytesprch = 2 and the content of a channels is outside the range -32768 to 32767. The number of times this happened is output. format: S A P Page 35 COMMANDS 25 April 86 arit [...] bytes,2 or arit [.... factor Specify that a the spectra involved in an add,sub,div,mul command is to be multiplied by individual factors and before the operation is done. format: arit [command] factor,, The content of is multiplyed by and the content of ( or the constant ) is multiplyed by before the aritmetic operation is done. S A P Page 36 COMMANDS 25 April 86 BACKGROUND The background command is used to initialize a background type, performe the fitting to the spectrum in a selected region, list background values, add and remove points from the background when defined by a set of points. You must always specify a least one subcommand. Background fits are kept until you specfify a new 'back init' a 'gauss init' or a 'clear' command. To move a background to another spectrum just select that spectrum. Remember that it must be displayed. init Initialize a background region for the current spectrum and define the type. The current position for low and high marker is used to define the region of interest i.e. the window Once initialzied the window markers can be moved without changing the background region. format: back init ! Normal linear or quadratic background. back init,p ! Init for a piece wise linear background. back init,ps ! Init for a spline background using cubic splines. ! The p and ps parameter require that you ! define the background by reading the cursor ! and uses the 'back point' command. fit Fit a background ( linear or quadradic to two region of the current spectrum ). The regions consist of one ranging from the lowmarker position defined at the time of 'background init' to a value to be read by the cross hair cursor, and from another reading of the cross hair cursor to the initial setting of the high marker. format: back fit ! Linear background. back fit,cons ! Constant background. back fit,lin ! Linear background. back fit,quad ! Quadradic background. S A P Page 37 COMMANDS 25 April 86 point Add a new point to the list which defines the background ( previously initialized either by 'back init,p' or 'back init,ps' ). The point and its value is taken from the position of the cross hair cursor. format: back point back point,, Do not use cursor but read from terminal. delete Delete a point from the table which defines the background. The marker closest to postion read from the cross hair cursor is removed from the list. You can also specify the markernumber in which case the cursor position is not used. format: back delete ! delete a point closest to cursor 1 back delete, ! delete point (marker) number e.g. back delete,3 list Print a list either of the background constants on the terminal obtained in a fit or the list of markers defined by 'back point' depending on the background type. format: back list,c ! list coefficients back list,p ! list the background points. subtract Subtract a background fit from the currently fitted spectrum. The resulting spectrum will be a new spectrum or replacing an existing spectrum depending on the specification of the save subcommand . format: background subtract [save,..] S A P Page 38 COMMANDS 25 April 86 save Specify the resulting spectrum for a background command. If subtract is specified the resulting spectrum is the current fitted spectrum minus the background, other wise it is the background itself. If a spectrumname is specified the new spectrum replaces the old spectrum. If a prefix is given a new spectrum with that prefix is created. If the save command is not given the spectrum will be saved on the spectrum file referenced by the default prefix. format: background save,s Save the background on file 's'. background save, Save the background on . background subtract save, Save the background subtracted spectrum on query Override the default query setting to ask for the new title when background or the background subtracted spectrum is saved. format: background query [...] noquery Override the default query setting to take the old title when when background or the background subtracted spectrum is saved. background noquery [...] S A P Page 39 COMMANDS 25 April 86 CHOP Chop an existing spectrum into smaller spectra. A twodimensional spectrum can be chopped into either twodimensional or into one dimensional spectra. size Define the size of each new spectrum by given the number of xchannels and ychannels. format: chop size, ... Cut spectrum into onedimensional spectra each with a length of channels chop size,, Cut a two dimensional spectrum into spectra with a size of * channels. channels Define the region of the original spectrum which has to be chopped. If it is not given the whole spectrum is chopped. format: chop channels,, ... The region from to is chopped. chop channels,,,, The window defined by these coordinates is chopped. to Define the prefix of the spectrum file on which the spectra are saved. If not defined the default prefix is used. query The title of each new spectrum is ask to be replaced. noquery The title and subtitle is taken from the original spectrum. COMPRESS Compress a set of spectra from 4 bytes/ channel to 2 bytes/channel. The normal spectrum layout is such that each spectrum channel is stored in 4 bytes = 32 bits. Since many 2d spectra have channels with a content in the range -32768 <= content <= 32767 it will be advantageous to store these in only 2 bytes. S A P Page 40 COMMANDS 25 April 86 This can be achieved by compressing the spectra. Note that some spectra may allready be compressed e.g. if they were declared by VAXEVA as 2 bytes /channel. The compress will create empty holes on the discfile but will not release these to other users. To do this pack the file afterwards. Only 2d spectra will be compressed. Note that compress works on spectra. To release space used by the spectrum file use the command pack and truncate. spectrum Define the list of spectra to be compressed. format: compress spectrum,,,..., Give a set of spectra. compress spectrum,,to<2> Compress all spectra from to . compress spectrum, Compress all spectra in a spectrum file. nocheck The program will not performe a scan of each spectrum in the list to check if the content is allowed for 2 byte storage if the 'nocheck' subcommand is specified. If nocheck is specified and a channel has a content outside the storage of 2 bytes/channel , only the lower 16 bits are retained in the result. CREATE Create an empty spectrum with a given size. This is usefull if you want to merge several spectra into one larger spectrum. size Define the size of the spectrum with the number of x and y channels. If the number of y channels is zero a one dimensional spectrum is created. format: create size,(,) the channels are 0 --> nx-1 and 0 --> ny-1 S A P Page 41 COMMANDS 25 April 86 channels Specify the first and last channel of the spectrum format: create size,,,(,) prefix Specify on which spectrum file the spectra will be saved. format: create prefix, [...] If no prefix is given the default file is used. bytes Define the number of bytes pr channel in the final spectrum. Allowed values are 2 and 4. For 1d spectra only 4 is allowed. format: create bytes, [...] DELETE Delete spectra from a spectrum file or delete a markerset. You specify a list of spectra to be deleted or a given markerset. Normally you will be asked if you really want to delete the item. format: delete [speclist] [options] delete spectra delete [markerlist] [options] spectrum Defines the spectra to be deleted. They are given as the usual list of spectra i.e. delete spectrum,,,... delete spec , etc delete spectrum,,to delete spectra si,si+1 ,... nolog Do not list the spectra or sets which are deleted. S A P Page 42 COMMANDS 25 April 86 noquery Do not ask if a spectrum or marker set is to be deleted. query Ask for each spectrum if it is to be deleted. This is the default. log Log the spectra which are deleted. This is the default. set Define the marker set to be deleted. The set is defined by it's number. format: delete set, The query and log options are as for delete spectra. S A P Page 43 COMMANDS 25 April 86 DECAY Fit a spectrum to a set of decay curves. The working is very much like the gauss fit command. Each decay curve is characterized by a decay constant and a height defined at a channel t0. init Initialize the decay curve fit. The region between the low and high marker is used as a fit region. The background is assumed to be constant and linear. curve Define a new curve by reading two cursor values. The two values must be larger than the background . An estimate of the decay is made by requiering the exponential curve to go through the two cursor values. fit Performe the fit to the spectrum. weight Determine the weight to be used in the fitting. Normaly the statistical errors of a channel content is used. It is possible to fit using a smoothed weight (by averaging over 3 channels before taking the statis- tical error. This will for low channel contents tend to keep the total number of count in the fit close to the total in the spectrum. format: decay weight,sm3 fit list Print a list of the current value of the parameters. fix Fix a parameter in the fit with a given value. format: decay fix,curve,,nto, fix height for decay decay fix,curve,,lambda, fix decay curve value for decay. decay fix,t0, set the zero point for the decay curves S A P Page 44 COMMANDS 25 April 86 ENERGY Command for creating /saving and using energy calibration for spectra. If an energy calibrations does not exists it must be initialized. This is done by the command 'energy init' .Some of the energy commands can be abbreviated. Energy calibrations are saved on the spectrum for which it is defined and will thus be saved for future reference. init Initialize the energy calibration. Specify the units on the axis e.g. KeV or nsec. The default is KeV. Specify the axis to 'x','y' axis. If spectrum is one dimensional the default is 'x'. format: energy init,, or ei,, unit : characterstring axis : characterstring one of x , y or z You can omit axis and/or unit e.g. energy init,MeV constant Input the calibrationsconstants. The calibration is defined as e = E0 + E1 * ch + E2 * ch**2 + E3 * ch**3 + E4 * ch **4 format: energy constant,,,,, or ec,,,,, You need to input at least two constants. The ones not given is set to 0.0. Constants can be written as e.g. 0.004 -3.45E-5 39. .0123 point Get a new point on a calibration by reading approbiate cursors or by reading channel numbers. format: energy point use cursor to get energy energy point, channel no is taken from input it further asks for energy energy point,, both channel and energy are taken from input S A P Page 45 COMMANDS 25 April 86 fit Performe a fit to the energy calibrations points to obtaine the calibration constants. You can specify the degree of the polynomial fit in the range (0-4). format: energy fit ! Fit with second order polynomial. energy fit, ! Fit with a polynomial of degree energy Get the channel number corresponding to a given energy. format: energy energy, or ee, channel Get the energy corresponding to a channel. The channel is either taken from the terminal input or from a peak found near the cross hair cursor. If the internal flag F1 is set two cursor reading are use to define a window within which the the centroid of the peak is calculated. format: energy channel Use the cursors to get an energy value. energy channel, Calculate energy from channel. or ech ech, list List either the calibration constants or the list of channel-energy pairs. format: energy list,c ! List the constants. energy list,p ! List the table of points. delete Delete a point from the table of calibration points. format: energy delete, S A P Page 46 COMMANDS 25 April 86 getcal Get a calibration from an existing spectrum to be used for the current spectrum. format: energy getcal, Get the calibration from spectrum setcal Save a calibration on one or more spectra. This can be used to set a given calibration on other spectra . When you make a fit or input the constants you need not to save because this is done . format: energy setcal, Set the calibration on one spectrum. energy setcal,,,..., Save the calibration on a set of spectra energy setcal, Set the calibration on all spectra with the prefix search Search for peaks in the currently displayed spectrum and show the energy on the display screen of the peak. You can control the sensitivity of the search by the "set calibr, " command. The default value of is 6. lsearch As search but output in addition a list of channel numbers and the corresponding enegies to the terminal. S A P Page 47 COMMANDS 25 April 86 EXTRACT Extract a the part of a spectrum which is inside a window or a region of a two dimensional spectrum and save the resulting spectrum in a new 2d spectrum. The content of the channels inside the window/region will be unchanged. The window is defined by the window markers. A region is defined by one or two marker sets as described in the region command. The projection can be made on the x or y axis. You can specify that the result is to be saved in an existing spectrum. It is analogous to the project command in the interpretation of the regions. format: extract [subcommands] spectrum The spectrum from which a new spectrum is extracted. If not given the current spectrum is used. format: extract spectrum, Spectrum is extracted region Define that the region boundaries are used to define the area from which the spectrum is extracted. format: extract region [...] ! Extract using the current region. window Define that the area to be extracted is the window. This is the default. save Specify the spectrum or prefix of a spectrum where the result will be put. format: extract save, Save on a new spectrum with a given prefix. extract save, Save if possible on spectrum . S A P Page 48 COMMANDS 25 April 86 noquery The program will not ask for new titles and subtitles but will use the current ones. Overrides the default setting of the query parameter. format: extract noquery [...] query The program will ask for new titles and subtitles . Overrides the default setting of the query parameter. format: extract query [...] S A P Page 49 COMMANDS 25 April 86 FUNCTION Aritmetic commands include the posisibility for multiplication and division of a spectrum by a function. The function and the parameters needed is defined by the function command. It can also be used to list the current values of the parameters. format: function [subcommands] define Define the function type and setup the default values for the given spectrum type. The possible types are presently: exp f(x) = a* exp(b * (x-x0)) def: a = 1.0, b = 1.0 x0 = 0.0 pol f(x) = a + b* u + c * u**2 + d * u **3 u = x - x0 def: a= 1.0, b=c=d=x0 = 0.0 pow f(x) = a * ( u**b) u >= 0 = 0.0 u < 0 def: a =1.0 , b = 0.0, x0 = 0.0 format: function define, e.g. func def,exp constant Change one of the constants . The constant is named by a, b, c, d or x0 respectively. format: function constant,, [.. subcommands] e.g. func const,a,0.98 func const,a,1.34 const,b,-0.076 list List on the terminal the current defined function and the parameter values. S A P Page 50 COMMANDS 25 April 86 GAUSS Main command for the sub commands which initializes and manipulates the fitting of a spectrum to a set of gaussian peaks. Only one dimensional spectra can be fitted. The peak shape can also be skewed gaussian and with an added exponential tail. Parameters can be fixed to specific values ass requested. The half width of the peaks are by default coupled to have the same value. It is though possible to let the half width have different values for different peaks. To make a gauss fit you should go through the following steps. 1. initialize the fit . 2. define the peaks by the cross hair cursor. 3. do the fit. It is possible to list the current values of peak positions etc. It is possible to delete a peak from the list defined thus saving the all ready defined peaks. The background can be displayed in addition to the peaks. init Initialize the fit. The region which is fitted is determined by positions of the low and highmarker (set by the window, low or high commands). The fit is performed on the current spectrum which must be displayed. format: gauss init ! initialze fit / draw the background guess. peak Add a peak to the list of peaks. The new position is taken from the cross hair cursor which will appear when the command is issued . The height is taken as the height above the background for the selected channel. If the same half width is assumed for all peaks then the estimate for the half width is taken from the first peak determined. It is therefore important that this is an isolated peak with a well determined half width. format: gauss peak use the cross hair cursor to get position gauss peak, use the integer value as the initial value. S A P Page 51 COMMANDS 25 April 86 delete Delete a peak from the list of peaks to be fitted. format: gauss delete Delete the last peak defined. gauss delete, Delete peak no defined. The i refers to the order in which the peaks are defined, NOT order of channels. fit Do the fitting to the current spectrum. You can specfy that you want to include a constant tail or to include a exp tail. format: gauss fit ! normal gauss fitting. gauss fit,tail ! fit with a tail. list List on the terminal the current values of background, tail parameters and the peak parameters. format: gauss list fix Fix a specified parameter for the following fit. The parameter can be specified in a symbolic way or by a number. Some parameters will be fixed even for future calls to the gauss fitting i.e. after a new gauss init has been called. i.e. the quadradic background, the constant tail, the exponential tail and the common half width. The following symbolic names are used: b0 : the constant for the background b1 : the first order term for background b2 : the second order term. ct : the constant tail th : the exponential tail height tw : the exponential tail width fwhm : the common half width peak : one of the peak parameters format: gauss fix,, ! Fix one of the parameters b0 --> fwhm gauss fix,peak,,heig, ! Fix the height gauss fix,peak,,pos, ! Fix the position gauss fix,peak,,fwhm, S A P Page 52 COMMANDS 25 April 86 ! Fix the half width ! of peak no e.g. gauss fix,fwhm,3.45 gauss fix,peak,3,pos,345.6 vary Specify that a parameter previously fixed shoul be varied. The format is as for fix. Please see help for that. e.g. gauss vary,b2 ! Have a quadradic background. set Set the half width to be the same or different for all peaks. format: gauss set,diff ! Set to different half widths gauss set,same ! Have a common half width. ! This is the default setting. disback Draw the background as defined by the linear or quadradic background. format: gauss disback g di subtract Subtract the gauss fit i.e. the content of the peaks not including the linaer or quadradic background and save in a new or existing spectrum. save Define where the subtracted spectrum should be saved. format: gauss sub save, ! save on new spectrum gauss sub save, ! save on an existing spectrum If the save is not given it tries to save the spectrum on file with the prefix s. S A P Page 53 COMMANDS 25 April 86 scale Change the current values of the peak heights and background values by an overall factor. Usefull when the gaussfit is move from one spectrum to next and the major change between the two spectra is a scaling. shift Change the current values of all peak positions by a fixed amount in channels. Usefull when fits are moved from one spectrum to another and the new spectrum is shifted relative to the first. weight This is an additional parameter to the fit command. It determines whether the normal statistical weight is used for chi**2 or whether a three point weight is used. This later description is good for low statistics peaks and gives a more accurate peakarea. (G.W.Phillips, Nucl.Instr.Methods 153(1978)449 ) format: gauss weight,normal fit !default gauss weight,sm3 fit ! 3 point smooth S A P Page 54 COMMANDS 25 April 86 INTEGRATE Integrate the current spectrum/spectra on the spectrum given as parameter within the limits. The limits are given by one of the subcommands whole/window/region . The default option is window. If a background is defined and the region over which the integral is calculated is completely inside the background region the area of the background and the area above the background is calculated as well. The area as well as the average channel number is output. format: integrate [subcommands...] spectrum Define the spectrum to be integrated. Only one spectrum can be given as parameter. format: spectrum, Spectrum with the spectrum reference will be integrated. whole The whole spectrum independent of the window markers will be integrated. format: whole all All spectra displayed will be integrated. This subcommand can not be used together with the 'spectrum' sub command. window The area to be integrated is defined by the window. i.e. the area enclosed by the windowmarkers. This is the default setting. moments In addition to the sum and average of the spectrum within the integrated area the second moment and the square root thereof is output. S A P Page 55 COMMANDS 25 April 86 INVERT Turn a two-dimensional spectrum around the diagonal y=x, that is exchange the content of the channels (i,j) and (j,i). During execution, a temporary spectrumfile is created on the output file, which must be able to hold both files during execution. format: invert spectrum, [save, query/noquery] spectrum Mandatory subcommand, that specifies the name of the spectrum to be inverted. format: invert spectrum,t63 save Turned spectrum is saved on the default spectrum file, unless the sub- command save specifies another connected file. The save-reference may be made by spectrum name or prefix. It is possible to use the same spectrum as output as the input. format: save,s3 or save,y query The program will prompt for changes to the input title and subtitle, and use the so changed titles for the output spectrum. If neither query or noquery has been specified action will be determined by the current value of the default setting. noquery Keep title and subtitle from input spectrum and use them for the output spectrum. S A P Page 56 COMMANDS 25 April 86 LIST List the header information of the spectra specified. The listing can be on the terminal, on a printfile or on a user specified data file. You should specify some spectra to be listed. The list command can also be used to list the content of a marker set. format: list [subcommands] spectrum The subcommands specifies what spectrum headers are printed. format: spectrum,,,..., Spectra , .. are listed. spectrum,,to All spectra from to are listed. spectrum, All spectra with the prefix are listed. e.g. list spec,s2,s4,t67 list spec,s on Specify the output device. The header listing will appear on the terminal as a default. To route it to a print file use the on subcommand. format: on,terminal list on the terminal on,printer list on a print file which can be routed by a 'purge' command on when you exit from the program. on,name the listing will be saved on a new file with the name 'name.dat'. e.g. list spec,s10,to15 on,printer set Define the marker set to be listed. The set is given as the number. format: list set, [options] S A P Page 57 COMMANDS 25 April 86 The options are otherwise as for list spectra. file List the headers of spectra from a spectrum tape written in VAX format. The tape to be listed is by default the input tape. format: list file,(,) [... If only is given only the header of that file is listed. tpout The tape from which the headers is read ( when file is specifed) is taken to be the outputtape. S A P Page 58 COMMANDS 25 April 86 MODIFY Modify the content of one channel in a spectrum. format: modify [spectrum,] channel,[,] content, spectrum Specify the spectrum to be used. If not given the current spectrum is selected. channel Specify the channel to be modifyed. For a two dimensional spectrum the x coordinate as well as the y channel must be given. e.g. modify .. channel,512 e.g. modify .. channel,64,37 .. content Specify the new content of the channel. If you do not give the new content the programs asks for it. The old and new content is output as information. S A P Page 59 COMMANDS 25 April 86 PROJECT Project a window or a region of a two dimensional spectrum. The window is defined by the two lower and upper markers. A region is defined by one or two marker sets as described in the region command. The projection can be made on the x or y axis. You can specify that the result is to be saved in an existing spectrum. format: project [subcommands] spectrum The spectrum to be projected. If not given the current spectrum is used. format: project spectrum, Projection is made of spectrum on Defines the axis on which the projection is made. format: project [...] on, Axis is either x or y. The default is x-axis. e.g. project on,y region Define that the region boundaries are used to define the area to be projected. format: project region [...] ! Project using the current region. window Define that the area to be integrated is the window. This is the default. save Specify the spectrum or prefix of a spectrum where the result will be put. format: project save, Save on a new spectrum S A P Page 60 COMMANDS 25 April 86 with a given prefix. project save, Save if possible on spectrum . noquery The program will not ask for new titles and subtitles but will use the current ones. Overrides the default setting of the query parameter. format: extract noquery [...] query The program will ask for new titles and subtitles . Overrides the default setting of the query parameter. format: extract query [...] S A P Page 61 COMMANDS 25 April 86 SELECT Select a spectrum as the current spectrum or select a markerset as current markerset . spectrum Select a spectrum. If the spectrum is displayed the spectrum indicator is modified to reflect the change. format: select spectrum, is a spectrum refence If spectrum, subcommand is not given the program asks for a spectrumname. An existing background or fit will be moved to the new spectrum. set Select a set. The set is given as the number indicated when the marker set was created. format: select set, If available then this set will become the current marker set. The display of regions and markers will be affected. = 0 means that no numbers are displayed and selected. format: select set, TITLE Change the title and subtitle for one or more spectra. You can give a group of spectra the same title and different subtitles. The program types the old title and expects one line of text giving the new title. The old text is conserved if you input an empty line i.e. only pressing . The title of a set of spectra can be changed but keeping the subtitle. Leading blanks in a title will save the corresponding characters in the old title. spectrum Select tby a spectrum list the spectra to have a new title format: spectrum,,,..., or spectrum,,to all spectra ,... S A P Page 62 COMMANDS 25 April 86 the is a spectrum reference like s2 e.g. title spec,s3,t4,s5 title spec,s11,to13 sametitle The spectra will be given the same title . The title is only asked for once, while the spectra can have individual subtitles. e.g. title spec,s15,to21 same sametitle No change of subtitle is requested. Only changes for the title is performed. e.g. gave spectrum s15 to s21 a new maintitle title spec,s15,to21 nosubtitle e.g. to give a series of spectra the same title but keeping the subtitles. title spec,s1,to12 same nosubtitle S A P Page 63 COMMANDS 25 April 86 TRANSFORM Transform a one dimensional spectrum by x --> g(x) thereby creating a new spectrum with a x scale which is changed. The counts are redistributed according to the function selected. The total integral is conserved. The command is used to setup the transformation type the constants involved in the function and squezing factors. The transformation is in details x -- > ( g(x) - g0) * g1. For description of g(x) see setup. The limits of the final spectrum is given by [z0,z1] The window selected of the original spectrum is [x0,x1] Note that the subcommands setup , evaluate and spectrum are mutual excluded. setup Define the function. Presently the available types are 1) polynomial i.e. g(x) = a + b*x + c*x**2 where a,b,c are constants which can be set. format: transform setup,polynomial 2) time of flight (relativistic) g(x) = Ekin = a*(1.0/sqrt(1.0-(c/(b-x))**2) - 1.0) a = moc**2 , b = N0, c = k format: transform setup,time 3) momentum transformation (relativistic) g(x) = a*((sqrt(1.0 + (d/a)**2*exp(2.0*c*(b-x))) - 1.0) a = m0c**2, b = N0, c = k , d = p0 format: transform setup,momentum constant Set a given constant to a value. format: transform constant,, [...] The value can be real/integer. S A P Page 64 COMMANDS 25 April 86 evaluate Calculate the transformed value of x using the current values of the constants. format: transform evaluate, spectrum Do the actual transformation by specifiing a spectrum name. format: transform spectrum, save Define where the transformed spectrum is saved either by giving a prefix or by giving an existing spectrum. format: transform spectrum, save, transform spectrum, save, noquery Use the old title without asking for a new title. query Do ask for a new title in any case. 2 list List the current type and parameters defined for the transformation. S A P Page 65 COMMANDS 25 April 86 T2TRANSFORM Transform a two dimensional spectrum by (x ,y )-->( g(x), g(y)) thereby creating a new spectrum .The counts are redistributed according to the function selected. The total integral is roughly conserved. The command is used to setup the transformation type the constants involved in the function and squezing factors. In short the channel content of the transformed spectrum is found by finding the channel which is mapped onto the final channel. The content is taken as a 3-point interpolated value of the original spectrum multiplied by the jacobian of the inverse transformation in the channel. This procedure will loose count but for spectra which are reasonable smooth a good result is produced. Channels with single counts are likely to disappear in the transformation. For this reason the output spectrum can be multiplied by a factor. It can be specified that only a recatangular region of the original spectrum is used for the transformation. The output spectrum can be specified to be of type I2 Note that the subcommands setup , evaluate and spectrum are mutual excluded. setup Define the function. This must be the first call to t2transform. Presently the available types are 1) linear. x --> a11*x + a12*y y --> a21*x + a22*y where the matrix elements a11,.. can be set by the constant subcommand. By default the matrix is initialized to the unit matrix. format: transform setup,linear constant Set a given constant to a value. format: t2transform constant,, [...] The value can be real/integer. e.g. t2transform cons,a11,0.87 cons,a22,0.75 S A P Page 66 COMMANDS 25 April 86 evaluate Calculate the transformed value of x using the current values of the constants. format: t2transform evaluate,, spectrum Do the actual transformation by specifiing a spectrum name. format: t2transform spectrum, save Define where the transformed spectrum is saved either by giving a prefix . If not given the spectrum file referenced by the default prefix is used. format: t2transform spectrum, save, noquery Use the old title without asking for a new title. This overrides the defualt setting for the query command. query Do ask for a new title in any case. 2 list List the current type and parameters defined for the transformation. S A P Page 67 COMMANDS 25 April 86 ZERO Clear the content of some channels of a spectrum. You specify a range of channels and a spectrum to be cleared. format: zero [spectrum,] channels,,[,,] spectrum Specify the spectrum to be cleared. Only one spectrum at a time can be cleared. If no spectrum is specified the current spectrum is selected. If the spectrum to be cleared is displayed a display command is issued by the program to update the display. channels Specify the range of channels to be cleared. For a one dimensional spectrum you must give the first and last channel to be cleared. For a twodimensional spectrum also the first and last y channel must be given S A P Page 68 COMMANDS 25 April 86 19.5 Spectrum Display. DISPLAY This is the general command for displaying a spectrum. Many different subcommand can be given to this command. Once a spectrum is displayed SAP/CHLOE remembers the layout of that spectrum for a while ( "A while" means that no more than 20 other spectra have been displayed before a spectrum is referenced again in a display command.) . One or more spectra can be displayed. Once a set of spectra have been displayed further display commands this set of spectra will be displayed with different options until a new list of spectra is given. A list of spectra can consist of just a single spectrum. In the case of two dimensional spectra up to 4 can be displayed at one time. One dimensional spectra can be displayed with a linear scale or with a logaritmic scale. Two dimensional spectra are displayed with different colors or with intensity patterns when no colors are available. Some of the parameters can be given default values when a new spectrum is displayed. See the commands 'set disdef,..' . The following is a list of the subcommand possible to the display command. Most of the subcommands have parameters associated. spectrum scale log lin shift color bin restore overlay roll channels z ymin expand cut spectrum Select one or more spectra to be displayed. format: spectrum,,,..., At most 20 spectra can be displayed at once. Up to 4 two dimensional spectra can be displayed at once. etc. are spectrum references see 'help spref'. scale Change the scale of one dimensional spectra on display. The initial setting is 1024 counts across the screen. The full scale indicates counts pr bin. If a large number of channels of a spectrum is displayed the content of teh channelks are binned before being displayed. format : scale,up ! increases the scale (peaks appears smaller) ! by a factor of two scale,down ! decrease the scale by a factor of two. S A P Page 69 COMMANDS 25 April 86 (peaks appear bigger) ! scale,,,..., ! spectrum will get a scale of 2** ! spectrum will get a scale of 2** ! ... ! spectrum and the rest will get a ! scale of 2** e.g. display scale,12 ! all spectra will be displayed with a full ! scale of 4096. log Change the layout of a one dimensional spectrum to a logaritmic display. format: log, ! the display of each spectrum will be ! shown with a decades. ! You can omit the e.g. log log,5 lin Change the layout of a one dimensional spectrum to a linear scale. The initial setting of the scale is linear. format: lin ! The spectra displayed will be shown with ! a linear scale. shift One dimensional spectra can be either displayed with a common x-axis or displayed with an displacement of 512/nospectra pixels between the x-axises in the y-direction. The subcommand will switch between these two modes. Initialy the spectra will be shown shifted. color Define the colors with which the one dimensional spectra are shown. The colors 1,2...7 are currently available for 1 dimensional spectra. The default color for a new spectrum is no. 1 ( currently red). If you have several spectra displayed these can have different colors. This can be set by having more colorvalues as parameters to the subcommand. format: display color,,,.., ... The first spectrum will get color , the second , the n'th and S A P Page 70 COMMANDS 25 April 86 the n+1 the color. e.g. disp color,1,2 ! spectrum color 1 ! spectrum color 2 ! spectrum color 2 z Change the lower and upper cut for a two dimensional contour display. For two dimensional spectrum only channels with a content between and are displayed. The initial settings for these parameters are 1 and 64. format: display z,, ... cut A two dimensional spectrum is displayed as a contour. The cuts defining various color levels are determined by the and the number of colors. You can make the cut in a linear or logaritmic way. The logaritmic cutting tends to smooth out statistical fluctuations .If your spectrum is manipulated it may be advantegous to use a linear representation . format: display cut,lin ! select a linear cutting display cut,log ! select a logaritmic cutting. NOTE. When logaritmic cutting is chosen must be non-negative otherwise it is modified to 0. bin A one or two dimensional spectrum can be binned before it is displayed. You can specify a bin factor in the x and y coordinate. The command performes automatic change of the binssize if the number of pixels is larger than available for the display in any direction. Factors may be changed if nessecary due to the no of pixels available on the display. format: display bin,, [subcommands..] display bin, [...] ! for oned The bin factors must be positive integers. restore Restore the spectra to show the whole spectrum. Low marker and high marker are set to the first and last channel respectively. format: display restore [subcommands] expand Expand the spectra displayed to show the region between the low marker and highmarker position . The expanded region can be S A P Page 71 COMMANDS 25 April 86 different on the various spectra shown. overlay Add a spectrum to the existing spectra displayed. The screen will not be cleared but the new spectrum will be shown in addition to the ones allready displayed. format: display overlay spec,.. [other subcommands] roll Roll a spectrum to the left or to the right with a given number of channels. A positive number will roll to the right, a negative to the left. format: disp roll, ymin Specify a lower limit for a one-dimensional spectrum. To be able to display negative counts in a spectrum you should specify a negative ymin. The lower limit for 2d spectra is set by 'display z,...' format: display ymin, channels Give the range in channel numbers which will be displayed. format: display channels,,last> [... subcommands] S A P Page 72 COMMANDS 25 April 86 CLEAR This command will remove a background fit, a gaussfit from the display. The background or gauss fit will there after be in a state of 'not initialized'. S A P Page 73 COMMANDS 25 April 86 19.6 Regions And Markers. CRMAR Create a markerset. A markerset has 3 attributes. These are 1. the kind i.e. the dimension normally 2. 2. the type Markers can be grouped in pairs or can be a collection of single markers. 3. the along parameter This defines along what coordinate axis the markers are sorted. The default is the x-axis. format: crmar [options] kind Define the kind of the markers. This must be a number 1,2 or 3. The kind correspond to the dimension of the spectra for which you want to apply the markers. 2d markers can be used to define regions. 1d markers can be used to integrate several windows/gates in one command. format: crmar kind, e.g. crmar kind,2 type The type can be of singles or pair type as explained above. format: crmar type,pair markers will be of pairtype (default) crmar type,sing markers will be of singles type. along The markers can be along x,y or z format: crmar along,x [kind,.. type,..] DAM Delete All Markers For this command please see the section under MARKER. S A P Page 74 COMMANDS 25 April 86 DMAR Delete Marker For this command please see the section under MARKER. HIGH Get a new position of the highmarker. If no parameters are given to the command the position by reading the cross hair cursor. format: high Read cursor 2 from display. high,[,] Set high marker to channel (if 2d the coordinate must be given too). LIST Command for listing of a set is list set,<...> See under list of spectrum for subcommands. LOW get a new position of the lowmarker. If no parameters are given to the command the position is taken by reading the cross hair cursor. format: low Read cursor 1 from display. low,{,} Set lowmarker to channel (if 2d the coordinate must be given too) . MARKER The marker commands will be used to performe the following operations on a marker: 1) add a new marker 2) move a marker 3) select a marker and 4) delete a marker. Marker coordinates will usually be given by the position of cursor 1 ( and cursor 2) when markrers are of pair type. The actual commands are mmar: move marker nmar: new marker smar: select marker dmar: delete marker S A P Page 75 COMMANDS 25 April 86 dam : delete all markers in a set nmar New marker. Read the position x,y coordinate from the cross hair cursor. If the marker comes in pairs read two values. The new marker will become current marker. It will be displayed as a X on the screen. The kind of the marker ( i.e. the kind of the set to which the marker belongs) must be the same as the dimension of the spectrum displayed. mmar Move marker. The cursor will appear. Input the new by moving to new position of marker and press a key. If the marker belongs to a 2-dimensional pair the other marker in the pair will also be moved. dmar Delete the marker nearest the cursor or a specific marker. If no marker is specified the cross hair cursor will appear Move it near the marker you want to delete. format: dm ! delete nearest marker dm, ! delete marker number smar Select the marker nearest the cursor or a specific marker. If no marker is specified the cross hair cursor will appear Move it near the marker you want to delete. format: sm ! select nearest marker sm, ! select marker number smar Delete all markers belonging to the currently selected marker set. MMAR Move the current marker. For This command please see the section under MARKER. S A P Page 76 COMMANDS 25 April 86 NMAR New Marker. For This command please see the section under MARKER. REGION Operate on a region. A region is defined by one or two markers set. It will be defined by one marker set if the type of the marker set is of pairtype otherwise of two sets. The boundary of a region is given by spline interpolating curves. The boundary may be displayed. format: region [options] define Define what marker sets are included in the region. format: region define, Region will be set1. (if pairtype). region define,, The region will be defined by set1 and set2 which both must be of single type. type Define the type of the interpolating curves between the markers. Presently linear curves and cubic splines are avalilable. format: region type,lin assume a linear connection region type,spline assume a spline curve display Turn the display of the region on and off format: region display,on display the region boundary. region display,off do not display the region boundary. S A P Page 77 COMMANDS 25 April 86 list List the status of the boundary. i.e. the set(s) which belong to the region and whether it is displayed or not. delete Delete the region definition. S A P Page 78 COMMANDS 25 April 86 RESTORE Restore a markerset from the values etc. previously saved on a discfile. format: restore from, set, e.g. restore from,alpha1 set,2 restore The name on which the markerset is. A file type of ".mrk" is assumed if not given. set Define the setnumber on which the markerset is to be saved. If not given it is saved on a new defined set. It may or may not over write an existing set. format: restore set, [from...] S A P Page 79 COMMANDS 25 April 86 SAVE Save a set markers on a discfile. The markerset is saved in ASCII readable text with all neccesary information so it can be restored . The set is not deleted. format: save set, on, set The number of the set to be saved. If not given the program asks for a set number. format: save set, [on,..] on The name of file on which the set is to be saved. A NEW file is created with that name. If the filetype is not given a type of ".mrk" is assumed. SAP/CHLOE tells you the full name of the file. S A P Page 80 COMMANDS 25 April 86 SMAR Select current marker. For further information for this command please see the section under MARKER. WINDOW Read the positions of the cross hair cursor two times and use their positions as the values of the low and high marker. The low and high markers specifies the regions when spectra are expanded, integrated printed, to be fitted to a background or gaussian set of peaks. This region is often refered to as a window. format: window,,[,,] Assign the window marker the x coordinates and . If the current spectrum is two dimensional then and must also be given. S A P Page 81 COMMANDS 25 April 86 19.7 Control Commands This set of commands can be used to display the content of various variables, to assign logical commands, get information on help and news, set program variables . ATTACH Attach the terminal to the master process if such exists. This means that the SAP/CHLOE program is temporarely suspended. It can be resumed by attaching the terminal to the subprocess which executes SAP/CHLOE. This can conveniently be done using the two symbols defined in sapassign 1 : start_sap ; start a subprocess executing sap 2 : return_to_sap ; attach terminal to sap process BELL This command will make the terminal bell sound twice. It is usefull to wake the sleepy user after execution of time consuming commands. COLOR Replace the entire colour table used for 2d spectra by reading a new color table from a file on disc or replace a seperate color in one of the overlay planes. For the normal user the later option is not usefull since it requires knowledge of the internal organisation of the colors. file Read a new colour table to be used for the 4115 display in the 2d mapping. format: color file, The name of the file is the full file specification e.g. sapdir:colortab.tab If the type of the file is not given the type is assumed to be ".tab". S A P Page 82 COMMANDS 25 April 86 group Change one of the colours in one of the overlays ( groups). The colour should be given as red, green, blue , each in the range 0 <= value <= 100 format: color group,,,,, The groups are 1: colour 1-7 single spectra 8-63 2d contour colours. 2: colour 1 background, fits 3: colour 1 text and markers Colour 0 is the general background colour. DATE Output the date and time to the terminal. DCL Spawn a subprocess. If a text is given as a parameter to the command that dcl command will be executed in the subprocess and control will return immediately to SAP. If no text is given a session is started in the subprocess. The prompt will be preceeded with SAP1> as long as the subprocess is active. To return control to sap issue a $logout command. examples: dcl,"show system/batch" dcl DUMP Dump the values of some of the internal data structures. The command is most usefull for the debugging in the case of software failures. subcommands: dump all Dump the maximum information. dump disp Dump the content of the displaydescriptors. S A P Page 83 COMMANDS 25 April 86 EXIT Exit from the Spectrum Analysis Program. The graphic screen will be erased. The program ask what should be done with the log file. The logfile containe all the commands given and the results as they appear on the screen. The only exceptions are commands which produces the output on a specific file as list and print. GRAPHICS Change the status of the display. The graphics device can be released and allocated using this command. on Allocate and initialize the display device. The display device is that pointed to by the logical name TEKTRONIX. off Terminate the use of the graphics device. It can then be used by other processes. HELP List the command available to the user and/or give further information on the commands. format: help [command-name] [subcommand-name] e.g. help display Gives a summary of display. or help display scale Describes the subcommand scale in display. help,all Gives all subcommands for a given command. help,all Gives the heading description of all commands. help,all all Gives the complete description of sap commands. BE AWARE OF THIS: it will produce a lot of output to the terminal which cannot be interrupted! S A P Page 84 COMMANDS 25 April 86 LOGICAL Main command for operating on logical commands. Depending on the subcommand you can get a listing of the logical commands assigned, add or remove one. See in the introduction for more on logical names. define Define a new logical command. The commandstring can be a simple name, or a string enclosed in double quotes ("....") .This last constructions allows you to have spaces in the commandstring. Ths commandstring can be a partial SAP/CHLOE command. logical define,, e.g. logical define,d,"display spectrum" remove Remove (delete) a logical name from the list of logical commands. format: logical remove, list List the commandstring associated with either all or a particulary logicalname. format: logical list, NEWS Get the latest news on changes and improvements of the spectrum analysis program. PURGE Will cause a printfile created by e.g. list or print command to be routed to the line printer. The print file is deleted at the same time. Do not confuse this command with the 'VAX-VMS' purge command. This is the same command as spool. S A P Page 85 COMMANDS 25 April 86 REPORT This will add to a file report.sap in sapdir a comment from a user about a specific subject. SAP/CHLOE will ask about your name, the subject and will allow you to input text describing the problem or the suggestion. By having this as a command you can report a given problem right away. It will though not be corrected immediately !!! S A P Page 86 COMMANDS 25 April 86 SET Change the value of a common parameter. The parameters which can be set are described in the subcommands. You can change runnumber, user_id, whether or not window markers track on more spectra, and some of the spectrum default values. The subcommands are: user wintrack f1 run disdef prefix query calibr axis tektronix resolution tapedevice frame plotter user Change the userid. The userid is saved in spectrum header when a new spectrum is created and listed on printer listings. format: set run, < user_id> is a name wintrack Determine how window markers are interpreted when several spectra are displayed. If the wintrack mode is set the program attempts to set the low /high marker to the same channel number if several spectra is displayed at one time. It works only with the window / low or high commands. This means that if you add a spectra to those displayed it will not get the same low/high as the other spectra unless you call one of the 3 commands. format: set wintrack,on Set the mode on set wintrack,off Turn the mode off this is the initial setting. f1 Set the status of the internal flag F1. The boolean status of F1 controls some features of the GAUSS and ENERGY commands. See their description for more information. format: set f1,on set f1,off S A P Page 87 COMMANDS 25 April 86 disdef Change a default value of a spectrum display layout parameter. format: set disdef,, parametername is one of the following 1. low : lowcut in 2d display. 2. high : highcut in 2d display. 3. binx : binning in x for 2d display. 4. biny : binning in y for 2d display. 5. showscale : if value is one the levels of a 2d display is shown at the side , but the available space for a spectum is reduced. 6. scale : linear scale in 1d display. 7. dec : no of decades in log display. 8. cut : set cutting mode to linear or logaritmic. 9. color : the default color for a 1d spectrum. 10.cutlin: Set a linear color mapping for 2d displays. 11.cutlog: Set a logaritmic color mapping for 2d displays. This is the initial default. prefix Change the default prefix. The default prefix defines the spectrum file to which spectra will be saved after a manipulation command. The initial value is 's'. query When spectra are created from existing spectra the title and subtitle for the new spectrum must be defined. The query parameter specifies whether the user is asked to give a new title or the old title is used. set query,on will imply the user to give the new title set query,off will imply that the old title is used calibr Set a significance factor for the "energy search" command. The significance means that the area above background is larger significance times the sqrt( background) S A P Page 88 COMMANDS 25 April 86 axis Set the axis flag on and off. It determines the layout of the display. If axis flag is set then an axis and a scale is displayed. format: set axis,on set axis,off grid If set then a grid is from the ticmarks on the ordinate axis. format: set grid,on set grid,off tektronix Set the size of the screen area which is used or display of the spectra. The default is 3600*2800 but you can conviently set it to a smaller value if you want to make a smaller picture. format: set tektronix,width, set tektronix,height, resolution The resolution of the grahic commands is determined by this command. If resolution is on the value of the coordinates are in 12 bits otherwise in 10 bits. The speed of the display is quiet a bit faster if 10 bits are used , but is clearly visible on a large size spectrum. tapedevice Associate a physical tapedevice to the internal logical tape names mt0 and mt1. format: set tapedevice,mt0, set tapedevice,mt1, e.g. set tapedevice,mt0,"MFA0:" S A P Page 89 COMMANDS 25 April 86 plotter Associate a plot device for the plot produced by the cplot and c2plot commands. The default is to create a file which can be output to the laser printer. The UGS graphics is also setup to be able to output to a versatec printer plotter. If you want to switch between device issue a spool command before the set command and the next plots. format: set plotter,qms set plotter,versatec frame The display layout is also controlled by the setting of the frame parameter. This only for 1d spectra since two-d spectra are always displyed with their frame. If it is set each spectrum is displayed with it's individual frame (axis) arround it. When it is set it may not be too usefull to use the shift setting for the display. format: set frame,on ! enable framing set frame,off ! disable framing NOTE. In normal cases the frame for the first spectrum in a list appear. SHOW A command to display on the user terminal various information on the running analysis program. The information to be shown is selected by the subcommand given. all Display all the available information. spec Display information on the spectrum files allocated to the running Spectrum Analysis Program. The names, number of spectra and used and unused blocks are displayed. command Display a list of all main command available to the user. These command may not all be described by the help command. S A P Page 90 COMMANDS 25 April 86 full Display the maximum information on each item. short Display the minimum information on each item. user Display the current value for the userid and the runnumber . tape Display information on the input and output tapes alloated to the program together with their first free file. time Show the amountof cputime, dio count etc used. vm Show the virtual memory allocated by calls to lib$getvm. SPOOL If plotfiles are generated by plot commands it is directed to the versatec printer/plotter. Make sure that power is on. If spool is not specified during a session it is spooled at exit time. If a printfile was specified it will be output to the lineprinter. format: print print print Only the print file is spooled. print plot Only the plotfile is spooled. WAIT Wait a specified number of seconds. The command is not very usefull unless you are repeating a command procedure in which some spectrum are updated, displayed and so on, and which uses the repeat command. It can be interrupted by a CTRL C. format: S A P Page 91 COMMANDS 25 April 86 wait, seconds >= 0 and <= 1000 S A P Page 92 COMMANDS 25 April 86 19.8 Commandfile Commands. Commandfile are usefull to combine several commands of SAP/CHLOE into a single series of keystroke. It can also be used to set various default parameters in a conveinient way. See also the introduction on command files in the Manual. CALL This command will change the input to be taken from a command procedure and can be used either from the terminal or from a command procedure already activated. CALL,[,,...] The file type of a command file is assumed to be .com unless explicitely givem with the name. The parameters will replace the keywords %1,%2,... if they are used as parameters in the command procedure. RESUME This command is used to return to a command procedure which temporarily has been suspended by a pause command. RETURN The command is used in a command procedure to return from the current procedure to the calling level, which may be the console or another command procedure. PAUSE This command may be used in a command procedure to suspend command execution from the procedure and temporarily take commands from the console. The user may give a RESUME command to return to the command procedure. If an error occured during the execution of a command in a command procedure SAP/CHLOE issues a PAUSE command so the user can react to the error. S A P Page 93 COMMANDS 25 April 86 TERMINATE This command is intended to be used by a user, when the console is invoked from a command procedure by a PAUSE command. This command will return back through all command procedure calls to the console. INDEX Aritmetic, 32 color, 81 add, 32 compress, 39 bytes, 34 copy, 27 compress, 33 cplot, 19 div, 33 create, 40 factor, 35 dam, 73, 75 fdiv, 33 date, 82 fmul, 33 dcl, 82 mul, 32 decay, 42 save, 34 deconnect, 28 shift, 34 delete, 41 smooth, 34 demount, 22 sqrt, 33 display, 68 sub, 32 dmar, 74 to 75 dump, 82 Background, 36 energy, 44 delete, 37 exit, 83 fit, 36 extract, 47 init, 36 function, 49 list, 37 gauss, 50 noquery, 38 graphics, 83 point, 37 hardcopy, 16 query, 38 help, 83 save, 38 high, 74 subtract, 37 inittape, 22 Bell, 81 integrate, 54 invert, 55 C2plot, 21 list, 28, 56 bin, 21 logical, 84 cuts, 21 low, 74 scale, 21 mmar, 75 Call, 92 modify, 58 Chop, 39 mount, 22 channels, 39 news, 84 noquery, 39 nmar, 75 to 76 query, 39 pack, 29 size, 39 pause, 92 to, 39 print, 16 Clear, 72 project, 59 Color prplot, 18 file, 81 purge, 84 group, 82 readtape, 23 Command, 5 region, 76 aritmetic, 32 release, 25 attach, 81 report, 85 background, 36 resequence, 31 bell, 81 reserve, 25 c2plot, 21 restore, 78 call, 92 resume, 92 chop, 39 return, 92 clear, 72 rewind, 25 save, 79 Decay, 42 select, 61 curve, 43 set, 86 fit, 43 show, 89 fix, 43 smar, 75, 80 init, 43 spool, 90 list, 43 t2ransform, 65 weight, 43 terminate, 93 Deconnect, 28 title, 61 Delete, 41 transform, 63 log, 42 truncate, 30 marker set, 41 unload, 25 nolog, 41 window, 80 noquery, 42 write, 26 query, 42 zero, 67 set, 42 Command connect, 27 spectra, 41 Command substitution, 6 spectrum, 41 Commandfile, 92 Demount, 22 Commandfiles, 5 Digital Commandsyntax, 5 vt240, 12 Commannd Display, 68 crmar, 73 bin, 70 Compress, 39 channels, 71 nocheck, 40 color, 69 spectrum, 40 cut, 70 Connect, 27 expand, 70 to 71 Copy, 27 log, 69 spectrum, 27 restore, 70 to, 27 roll, 71 Cplot, 19 shift, 69 channels, 20 ymin, 71 chprmm, 20 z, 70 energy, 21 Display layout, 89 fit, 20 Dmar, 74 to 75 log, 20 Dump information, 82 max, 20 spectrum, 20 Energy, 44 Create, 40 channel, 45 bytes, 41 constant, 44 channels, 41 delete, 45 prefix, 41 energy, 45 size, 40 fit, 45 Create marker set, 73 getcal, 46 Crmar, 73 init, 44 along, 73 list, 45 kind, 73 lsearch, 46 type, 73 point, 44 Ctrl, 9 search, 46 Ctrl, 9 setcal, 46 Current spectrum, 61 Exit, 83 Extract Dam, 73, 75 noquery, 48 Daphne spectra, 4 query, 48 Date, 82 region, 47 Dcl, 82 save, 47 spectrum, 47 long, 28 window, 47 on, 29, 56 set, 29, 56 F1 flag, 45, 86 spectrum, 28, 56 First free file, 10 tpout, 29, 57 Function, 49 Logfile, 7 constant, 49 Logical, 84 define, 49 define, 84 list, 49 list, 84 remove, 84 Gauss Logical commands, 6 delete, 51 Low marker, 74 disback, 52 fit, 51 Marker, 74 fix, 51 Mmar, 75 init, 50 Modify, 58 list, 51 channel, 58 peak, 50 content, 58 save, 52 spectrum, 58 scale, 53 Mount, 22 set, 52 shift, 53 News, 8, 84, 86 subtract, 52 Nmar, 75 to 76 vary, 52 weight, 53 Outputtape, 10, 22 Graphics off, 83 Pack, 29 on, 83 file, 30 prefix, 30 Hardcopy, 16 Parameters, 5 Help, 7, 83 Pause, 92 High, 74 Prefix, 4 Print, 16 Inittape, 22 bin, 17 Inputlines, 5 channels, 17 Inputtape, 10, 22 format, 17 Integrate on, 16 all, 54 spectrum, 17 moments, 54 whole, 17 spectrum, 54 window, 17 whole, 54 Project, 59 window, 54 noquery, 60 Integration, 54 on, 59 Interrupt, 9 query, 60 Invert region, 59 noquery, 55 save, 59 query, 55 spectrum, 59 save, 55 window, 59 spectrum, 55 Protect, 10, 22 Invert spectra, 55 tpin, 23 tpout, 23 Laserprinter plot, 20 Prplot, 18 Lisa spectra, 4 bin, 18 List, 28, 56 channels, 19 file, 29, 57 cut, 19 on, 18 full, 90 spectrum, 18 short, 90 values, 19 spec, 89 whole, 19 tape, 90 window, 19 time, 90 Purge, 84 user, 90 vm, 90 Readtape, 23 wait, 90 files, 23 Smar, 75, 80 format, 23 Spawn, 82 to, 23 Speakesay, 5 Region, 76 Spectrum define, 76 header, 7 delete, 77 name, 8 display, 76 title, 7 list, 77 Spectrumfile, 3 type, 76 Spool, 90 Release, 25 Subcommand, 5 Report, 85 Resequence, 31 T2ransform log, 31 setup, 65 new, 31 T2transform, 65 nolog, 31 constant, 65 spectrum, 31 evaluate, 66 Reserve tapestation, 25 save, 66 Restore, 78 spectrum, 66 from, 78 Tape set, 78 allocation, 9 Rewind, 25 Tektronix 4114, 11 Save, 79 4115, 12 on, 79 dma interface, 12 set, 79 Title, 61 Save marker set, 79 nosubtitle, 62 Select, 61 sametitle, 62 set, 61 spectrum, 61 spectrum, 61 Transform, 63 Set constant, 63 axis, 88 evaluate, 64 calibr, 87 noquery, 64, 66 disdef, 87 query, 64, 66 f1, 86 save, 64 frame, 89 setup, 63 grid, 88 spectrum, 64 plotter, 89 Truncate, 29 to 30 prefix, 87 file, 30 query, 87 prefix, 30 resolution, 88 tapedevice, 88 Unload, 25 tektronix, 88 user, 86 Wait, 90 wintrack, 86 Window, 74, 80 to 81 Show Write all, 89 format, 26 command, 89 spectrum, 26 Write spectra, 26 channels, 67 spectrum, 67 Zero, 67