Control

Available commands: @macro_file , CLOSE , GOTO , IF , label_statement: , MAXERR , MKFILE , PARAMETER , PAUSE , pipe , QUIT , RESET , RETURN , REWIND and SYSTEM .

Control commands are used to change the status of either the program or the input-output files. For example it is possible for a user to call a system command or to create a sub-process without terminating EDPDB.

@macro_file

Read and execute commands from an existing macro file.

Function: Control

Syntax:
@macro_file [parameters]

Note:
1) The macro_file is the file name of a macro. The default file type is .edp.
2) A macro file can call other macro files. The number of nesting levels can be up to 9.
3) If no directory information is used in the file name, `@' will try to call the macro file in the current directory first. If unsuccessful, the file in the default directory will be used if exists. The default directory is defined with SETENV command.
6) A macro file can be used to customize the initial configuration of EDPDB, either as the parameter of the /EDPINI qualifier of EDPDB command in a VMS system, or as the fifth argument of the edpdb program in a unix system.

See also: GOTO, IF, MKFILE, RETURN and SETENV

Examples:
1) The following is an example macro, print.edp, that output the ON atoms to a printer. 

      ! print.edp: output the ON atoms to the laser printer
      write tmp.pdb
      close
      system print/que=laser/delete tmp.pdb
2) Run a macro file, test.edp, in the directory [user.edp_lib]. The two parameters will be passed to the macro to replace $(p1) and $(p2). 
      @[user.edp_lib]test parameter_1 parameter_2
The user may define his/her own keyword to call this macro. For example, 
      alias  my_command @[user.edp_lib]test
      setenv echo off
      my_command parameter_1 parameter_2

CLOSE

Release the output PDB file opened by a WRITE command.

Function: Control

Syntax:
CLOSE

Note: It is allowable to close an unopened file.

See also: APPEND and WRITE

Examples:
1) Print out the current ON atoms 

      write tmp.pdb
      close
      system print/delete tmp.pdb

GOTO

Look for the first occurrence of a label statement in a macro file that follows the GOTO statement (in a circular way) and matches the given label. If the search succeeds, it sends the control to the next command of the label statement. If it fails, it closes the macro file and generates an error message.

Function: Control

Syntax:
GOTO label

Note:
GOTO command can only used within a macro.

See also: label_statement: and $(parameter)

Examples:
1) In a macro, one may have the following structure. The program will skip command_set_1, execute command_set_2 and return to the upper level command. 

      goto $(p1) ; $(p1) can be label1, label2 or label3
      label1:
      ...(command_set_1)
      return
      label2:
      ...(command_set_2)
      return
      label3:
      ...(command_set_3)
      return
2) Construct a loop running through 1 to 100 
      parameter i = 1
      loop:
      ...
      parameter i + 1 100 exit
      goto loop

IF

Conditionally excute one command.

Function: Control

Syntax:
IF ( [-x] parameter_name operator value ) command

Note:
-x is one of the following: -s (for a string), -r (a real number), and -i (an integer number). The default is -s.
parameter_name is the name of a parameter which has been defined with the command PARAMETER .
operator is one of the following: == (equal), /= (not equal), >= (not less than), and <= (not greater than).

See also: GOTO .

Examples:
1) In the following program, the macro fix_leu will be skipped, and the macro fix_val will be excuted. 

      parameter res = val
      ...
      if ( res == leu ) @fix_leu
      ...
      if ( res == val ) @fix_val

label_statement:

Put a mark in a macro file for the GOTO command.

function: Control

Syntax:
label:

Note: A label starts with an alphabetic character and is followed by a colon `:'. There is no space allowed before or within the label, (leading space(s) may cause the label statement to be unrecognizable). The label may contain up to max_num_chars characters.

See also: GOTO command and $(parameter)

Examples:
1) In a macro, one may have the following structure. If the $(p1) is assigned to label2, the program will skip command_set_1, execute command_set_2 and return to the upper level. 

      goto $(p1)
      label1:
      ...(command_set_1)
      return
      label2:
      ...(command_set_2)
      return
      ...

MAXERR

Set the maximum tolerable number of errors.

Function: Control, Information Syntax:
1) MAXERR
2) MAXERR max_err [(EXIT, QUIT)]

Note:
1) The first form shows the currently defined maximum number of errors as well as the number of currently accumulated errors.
2) The second form sets the value of max_err which is the maximum tolerable number of errors, and initializes the number of currently accumulated errors to zero. The initial default is that max_err=256.
3) If the option EXIT is used, the program will return to the upper level whenever the number of errors is greater than max_err. If the option QUIT is used, the program will quit in the case that the number of errors becomes greater than max_err. The default option is QUIT.
4) To prevent an infinite loop, the number of accumulated errors increases by 1 whenever a REWIND command (with blank option) is used.
5) To prevent an infinite ALIAS substitution, the number of errors increases for each substitution.

Examples:
1) Show the current maximum number of errors. 

      maxerr
2) Set the maximum number of errors to 32 and choose EXIT option. 
      maxerr 32 exit

MKFILE

Create an ascii file, eg. a macro.

Function: Control

Syntax:
MKFILE file_name [eof]

Note:
1) eof is a character string to mark the end of the file. The default is "eof".
2) MKFILE command closes the previous file open by MKFILE.
3) The default file type is ".edp".

See also: @macro_file

Examples:
1) Create a macro "test" and use it. 

     mkfile test eof
     initialize
     zone $(p1)
     analyze
     eof

     @test 100
     @test 120
     @test 140

PARAMETER

Define or show variables, include the pre-defined variable P1, ... P8 and user-defined variables. The current version allows up to 20 variables, including the eight reserved ones. The name of each variable contains up to eight characters.

Function: Control, Definition, Information

Syntax:
1) PARAMETER [Pn]
2) PARAMETER Pn = [value]
3) PARAMETER Pn ? [prompt_string] [default_value] [(EXIT, REPORT) ]
4) PARAMETER Pn (+, -) step_size limit [(EXIT, REPORT)]
5) PARAMETER Pn group_id (ENTRY, ATOM, RESIDUE, CHAIN, ID, X, Y, Z, W, B) [(EXIT, REPORT) ]

Note:
1) The Pn is one of the P1, ... P8 or a user-defined variable. If defined, the value of Pn will replace the text string $(Pn) in an input statement read from a macro file.
2) The first form shows the current definition of Pn. The default is every currently defined variables.
3) The second form assigns a value to Pn. The value is a character string in general. If the character string contains a space or comma, it should be enclosed with a pair of quotation marks (or other delimiters). Assigning a null string (the default) is equivalent to delete that parameter.
4) The third form inquires a value for Pn when executed. The default prompt_string is "input ". The default_value will be assigned to Pn if the respond to the inquiry is a . The default default_value is the current Pn value. Control-Z (VMS) or Control-D (unix) (ie. end-of-file) will cause EXIT from the macro or an error status, depending on the option specified. The default option is to REPORT error.
5) In the fourth form, the parameter Pn will be increased or decreased by the step_size which usually is an integer; the limit set the limit condition for the loop control; the default choice at the end of the loop is to REPORT error.
6) The fifth form gets a variable value from the first record of a specified group and delete the record from the group. An empty group gives a limit condition which causes either EXIT or an error report.

See also: @macro_file, $(Pn), ALIAS, REWIND, SETENV DELIMITER and maximum number of parameters.

Examples:
1) List the current P1 parameter 

      parameter p1
2) Define P1 as number 5. 
      parameter p1 = 5
3) Define P2 as a text string (eg. This is a test.). 
      setenv tolower off
      parameter p2 = 'This is a test'
4) Inquiry RES_TYPE on the terminal, with ala as the default. 
      parameter res_type  ?  'res_type? ' 'ala'
It appears on the terminal as 
      res_type? [ala] _____
5) Construct a loop in a macro to handle residues 1 through 100, one residue at a time. The parameter P1 should be initialized as 1, when the macro is called. 
      ! beginning of the macro
      ...
      zone $(p1)
      ...
      parameter p1 + 1 100 exit
      rewind
6) Construct a loop in a macro to handle chain a through z, one chain at a time. The parameter P1 should be initialized as a, when the macro is called. 
      ! loop thru a to z
      parameter chain = a
      loop:
      chain $(chain)
      ...
      parameter chain + 1 z exit
      goto loop
7) Construct a loop in a macro to loop through every amino acid residues. 
      ! loop thru every a.a. residues
      group aa from { ca }
      loop:
      parameter doit aa id
      zone $(doit)
      ...
      goto loop

PAUSE

Pause the program, useful for saving the message on the terminal screen when executing a macro file. Function: Control

Syntax:
PAUSE

Note:
The PAUSE command is deactivated by SETENV INTER NO command. PAUSE will only work in interactive mode.

See also: PARAMETER, SETENV INTER and @macro_file

Examples:
1) In a macro, a PAUSE command can be used to display interesting data, which otherwise will pass the terminal too quickly. For example, a macro containing the following command is handy for taking an overall look at a PDB file. 

      ! overall information ...
      zone all
      zone
      pause
      atom 
      pause
      residue 
      pause
      analyze
      pause

pipe

Starting from v97b version, a unix-like pipe mechanism is built in EDPDB for logical-OR & AND selections etc. (This mechanism is exclusive with the old from-phrase selection mechanism.)

Function: Control

Syntax:
1) { selection1 | selection2 | ... | selectionN }
2) command1 \ command2 \ ... \ commandN

Note:
1) The first form is used for logical-AND selection.
2) The second form is used for logical-OR selection.
3) The symbol "{" saves the current ON atoms to the group "0000", initializes the ON-atom buffer, and sets ALL to be the selection pool.
4) The symbol "}" reloads the group "0000" back to the ON-atom buffer.
5) The symbol "|" loads the current ON-atom buffer to the selection pool, and initiallizes the ON-atom buffer.
6) The symbol "\" sets ALL to be the selection pool.

Examples:
1) select CA atoms of PHE residues from chain A. 

      { ca | chain a | residue PHE }
      list
2) select both CB atoms and main chain atoms (ie. N, CA, C and O) 
      atom cb \ main

QUIT

Terminate EDPDB without writing a new PDB coordinate file.

Function: Control

Syntax:
1) QUIT [SAVE]
2) control-Z (for VMS)
or control-D (for unix)

Note:
1) The optional SAVE will save both the .edp file which contains a list of the completed commands and the .scr file which stores some intermediate result. Both of these two files will be deleted with the default QUIT or EXIT commands.
2) The second form is the same as QUIT SAVE.

Examples:
1) Output the ON atoms to a PDB file called new_coor.pdb, terminate EDPDB and save the .edp file and the .scr file. (Note that the EXIT command will not save the .edp and .scr files). 

      write new_coor.pdb
      quit save

RESET

Reread all records from the original PDB file(s). All prior modifications to the records will not be save. The selection switch is set to INCLUDE (ie. ON). The ON atom buffer is initialized to empty.

Function: Input, Control

Syntax:
RESET

See also: INITIAL and READ

Examples:
1) Erase any modification made to the records 

      reset

RETURN

Quit from a macro file.

Function: Control

Syntax:
RETURN

Note: It has no effect as a top level command.

See also: GOTO and $(Pn)

Examples:
1) In a macro, one may have the following structure. The real parameter of $(P1) determines which part of the macro will be executed. 

      goto $(p1)
      label1:
      ...
      return
      label2:
      ...
      return
      label3:
      ...
      return

REWIND

Rewind the working files

Function: Control

Syntax:
1) REWIND
2) REWIND (EDP, SCR, PDB}

Note:
1) The first form rewinds the currently executed (lowest level) macro file.
2) According to the options chosen, the second form rewinds the recording (.edp) file, the scratch (.scr) file or the currently opened PDB file, respectively.

See also: FILE and WRITE

Examples:
1) Create a macro, test.edp, of a loop structure. 

      ! test.edp : a loop macro
      ...
      parameter P1 + 1 $(p2) exit
      rewind
One can run this macro 100 times, starting from (P1 = 1) and ended when (P1 > 100). 
      @test 1 100

SYSTEM

Execute a system command (eg. a DCL command in a VMS system or a c-shell command in a unix system) or create a subprocess without terminating EDPDB. (Bug!)

Function: Control

Syntax:
SYSTEM [[WAIT] system_command]

Note:
If the option WAIT is chosen, EDPDB will wait until the sub-process finishes. This can be used to synchronize related calculations.

Examples:
1) Spawn a subprocess 

      system
2) Print out the ON atoms. 
      write tmp.pdb
      close
      system print/delete tmp.pdb
3) Run a VMS command file (eg. test.com), and wait until it finishes. 
      system wait @test
Copyright 1995, Cai X.-J. Zhang, All Rights Reserved.