1 ICR

 ICR$LIBRARY:ICR contains a  number  of  generally  useful  subroutines
 developed  at  the Institute for Cancer Research.  Except where noted,
 these routines are language independent.

 A description of each routine may be displayed  by  typing  "HELP  ICR
 subr-name".

 A table of arguments for each subroutine or function may be  displayed
 by typing "HELP ICR subr-name CALL".  An explanation of the codes used
 in the table of arguments may be displayed by typing "HELP ICR DATA".
2 Data_types

 A table of arguments for each subroutine or function may be  displayed
 by typing "HELP ICR subr-name CALL".

 The data type encoding is as follows:

             <data type code>*<size>[(<array size or '*'>)]

 Data type codes are:

         1.  C -- Complex.
         2.  F -- Standard type floating point.
         3.  G -- "G" type floating point.
         4.  H -- "H" type floating point.
         5.  I -- Integer.
         6.  S -- String.
         7.  O -- Other (explained in the parameter description).


2 ICR_ADDQUAD
 
                           ICR_ADDQUAD(A,B,C)

 This procedure adds two quadword integers ('A' abd  'B')  and  returns
 the sum in 'C'.
3 Calling_sequence
 
                           ICR_ADDQUAD(A,B,C)

     Name             Mechanism   Type          I/O
                      Description
  
     A                Reference   I*8           Input only
  
     B                Reference   I*8           Input only
  
     C                Reference   I*8           Output only
                      Resultant quadword.
2 ICR_BKSCAN
 
        LOCATION = ICR_BKSCAN(STRING,SCAN_STRING,START_LOCATION)

 Scans STRING starting at START_LOCATION,  returns  location  of  first
 character in STRING which is also in SCAN_STRING.
3 Calling_sequence
 
        LOCATION = ICR_BKSCAN(STRING,SCAN_STRING,START_LOCATION)

     Name             Mechanism   Type          I/O
                      Description
  
     LOCATION                     I*4           Output only
                      Location of first character in  STRING  which  is
                      also        in        SCAN_STRING.         Equals
                      MAX(START_LOCATION,LEN(STRING)+1) if whole STRING
                      is scanned.
  
     STRING           Descriptor  S**           Input only
                      Character variable to be scanned.
  
     SCAN_STRING      Descriptor  S**           Input only
                      Character variable containing characters to  scan
                      for.
  
     START_LOCATION   Reference   I*4           Input only
                      Position in STRING at which to begin scanning.
2 ICR_BUMP_PRIORITY
 
                        ICR_BUMP_PRIORITY(BUMP)

 Allows an image to  alter  (if  it  has  ALTPRI  privilege)  its  base
 priority.   An exit handler is declared to reset the original priority
 when the image exits or is aborted.  The image must be installed  with
 some privilege in order to insure that the reset takes place.
3 Calling_sequence
 
                        ICR_BUMP_PRIORITY(BUMP)

     Name             Mechanism   Type          I/O
                      Description
  
     BUMP             Reference   I*4           Input only
                      Integer  specifying  a  relative  change  to  the
                      image's original base priority.
2 ICR_COMPQUAD
 
                     COMPARISON = ICR_COMPQUAD(A,B)

 This function compares two quadword, signed integers and returns -1 if
 'A'  is  less  than 'B', 0 if they are equal, and +1 if 'A' if greater
 than 'B'.
3 Calling_sequence
 
                     COMPARISON = ICR_COMPQUAD(A,B)

     Name             Mechanism   Type          I/O
                      Description
  
     COMPARISON                   I*4           Output only
                      The sign of the difference of the two parameters.
  
     A                Reference   I*8           Input only
  
     B                Reference   I*8           Input only
2 ICR_$CONNECT
 
                       STATUS = ICR_$CONNECT(RAB)

 This function invokes the RMS $CONNECT macro.

 May be used with ICR_$OPEN to open a  file  from  a  Fortran  useropen
 routine.
3 Calling_sequence
 
                       STATUS = ICR_$CONNECT(RAB)

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code.
  
     RAB              Reference   O             Input/output
                      An RMS record access block.
2 ICR_EDIV
 
                            ICR_EDIV(A,B,C)

 This routine divides the quadword 'A' by the longword 'B'  and  stores
 the  result  in  the  longword 'C'.  The programmer is responsible for
 insuring that no overflow can result.
3 Calling_sequence
 
                            ICR_EDIV(A,B,C)

     Name             Mechanism   Type          I/O
                      Description
  
     A                Reference   I*8           Input only
                      Dividend.
  
     B                Reference   I*4           Input only
                      Divisor.
  
     C                Reference   I*4           Output only
                      Quotient.
2 ICR_EMUL
 
                            ICR_EMUL(A,B,C)

 This routine multiplies two longwords ('A' and  'B')  and  stores  the
 result in the quadword 'C'.
3 Calling_sequence
 
                            ICR_EMUL(A,B,C)

     Name             Mechanism   Type          I/O
                      Description
  
     A                Reference   I*4           Input only
                      Multiplicand.
  
     B                Reference   I*4           Input only
                      Multiplier.
  
     C                Reference   I*8           Output only
                      Product.
2 ICR_GET_COMMAND
 
            STATUS = ICR_GET_COMMAND(PROMPT,COMMAND,LENGTH)

 Read a command from the command line if present or the  terminal.   If
 the   command   came   from   the  command  line,  the  next  call  to
 icr_get_command will return end-of-file status.  If the  command  came
 from  the  terminal,  end-of-file will be returned when the user types
 control-z.
3 Calling_sequence
 
            STATUS = ICR_GET_COMMAND(PROMPT,COMMAND,LENGTH)

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code.
  
     PROMPT           Descriptor  S**           Input only
                      Command prompt string or a blank for no prompt.
  
     COMMAND          Descriptor  S**           Output only
                      Command line.
  
     LENGTH           Reference   I*4           Output only
                      Length of command not including blank padding for
                      fixed length strings.
2 ICR_GLOBAL_SYMBOL
 
          STATUS = ICR_GLOBAL_SYMBOL(SYMBOL_NAME,SYMBOL_VALUE)

 Create a DCL global symbol.
3 Calling_sequence
 
          STATUS = ICR_GLOBAL_SYMBOL(SYMBOL_NAME,SYMBOL_VALUE)

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code
  
     SYMBOL_NAME      Descriptor  S             Input only
                      Character  variable  or  literal  containing  the
                      symbol name string.
  
     SYMBOL_VALUE     Descriptor  S             Input only
                      Character  variable  or  literal  containing  the
                      symbol value string.
2 ICR_LEN_TRIM
 
                     LENGTH = ICR_LEN_TRIM(STRING)

 This function returns the length of  a  character  variable  excluding
 trailing blanks.
3 Calling_sequence
 
                     LENGTH = ICR_LEN_TRIM(STRING)

     Name             Mechanism   Type          I/O
                      Description
  
     LENGTH                       I*4           Output only
                      The length of STRING excluding trailing blanks.
  
     STRING           Descriptor  S**           Input only
                      Character variable or quoted literal.
2 ICR_LOCAL_SYMBOL
 
          STATUS = ICR_LOCAL_SYMBOL(SYMBOL_NAME,SYMBOL_VALUE)

 Create a DCL local symbol.
3 Calling_sequence
 
          STATUS = ICR_LOCAL_SYMBOL(SYMBOL_NAME,SYMBOL_VALUE)

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code
  
     SYMBOL_NAME      Descriptor  S             Input only
                      Character  variable  or  literal  containing  the
                      symbol name string.
  
     SYMBOL_VALUE     Descriptor  S             Input only
                      Character  variable  or  literal  containing  the
                      symbol value string.
2 ICR_$OPEN
 
                        STATUS = ICR_$OPEN(FAB)

 This function invokes the RMS $OPEN macro.

 May be used with ICR_$CONNECT to open a file from a  Fortran  useropen
 routine.
3 Calling_sequence
 
                        STATUS = ICR_$OPEN(FAB)

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code.
  
     FAB              Reference   O             Input/output
                      An RMS file access block.
2 ICR_$PARSE
 
     STATUS = ICR_$PARSE(FILE_NAME,[DEFAULT_NAME],[EXPANDED_NAME])

 This  function  is  an  interface  to  the  RMS  $PARSE  macro.    The
 "expanded_name"  buffer  optionally  receives  the  file specification
 string resulting  from  the  translation  of  logical  names  and  the
 application  of  optional  default file specification information from
 "default_name" to the  original  file  specification  in  "file_name".
 "Expanded_name" should be be at least 128 characters, if fixed length.

 The same variable may be used for 'file_name' and 'expanded_name'.

 This routine may be used with ICR_$SEARCH to do  wild  card  character
 processing.
3 Calling_sequence
 
     STATUS = ICR_$PARSE(FILE_NAME,[DEFAULT_NAME],[EXPANDED_NAME])

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code.
  
     FILE_NAME        Descriptor  S**           Input only
                      Standard VAX/VMS file specification to be  parsed
                      (can include wild card characters).
  
     DEFAULT_NAME     Descriptor  S**           Input only
                      The default file specification.
  
     EXPANDED_NAME    Descriptor  S**           Output only
                      The expanded file specification.
2 ICR_PARSE_FILE
 
    STATUS = ICR_PARSE_FILE(FILE_STRING,[FILE_SPEC],[NODE],[DEVICE],
             [DIRECTORY],[FILE_NAME],[EXTENSION],[VERSION])

 This function extracts the file  specification  at  the  beginning  of
 file_string  and optionally returns it in file_spec, and its component
 fields in node, device, directory, file_name, extension, and version.
3 Calling_sequence
 
    STATUS = ICR_PARSE_FILE(FILE_STRING,[FILE_SPEC],[NODE],[DEVICE],
             [DIRECTORY],[FILE_NAME],[EXTENSION],[VERSION])

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code.
  
     FILE_STRING      Descriptor  S**           Input only
                      A  file  specification,  optionally  preceded  by
                      blanks  or  tabs,  which may be followed by other
                      text.
  
     FILE_SPEC        Descriptor  S**           Output only
                      The file specification found at the beginning  of
                      file_string,  or the null string if bad status is
                      returned.
  
     NODE             Descriptor  S**           Output only
                      The node part of file_spec.
  
     DEVICE           Descriptor  S**           Output only
                      The device part of file_spec.
  
     DIRECTORY        Descriptor  S**           Output only
                      The directory part of file_spec.
  
     FILE_NAME        Descriptor  S**           Output only
                      The filename part of file_spec.
  
     EXTENSION        Descriptor  S**           Output only
                      The extension part of file_spec.
  
     VERSION          Descriptor  S**           Output only
                      The version part of file_spec.
2 ICR_QUAD_TO_D
 
                     RESULT = ICR_QUAD_TO_D(QWORD)

 This function converts  a  quadword  integer  to  a  double  precision
 floating  point  number.   Note  that  precision  will be lost in this
 conversion as double precision floating point  has  only  56  bits  of
 precision.
3 Calling_sequence
 
                     RESULT = ICR_QUAD_TO_D(QWORD)

     Name             Mechanism   Type          I/O
                      Description
  
     RESULT                       F*8           Output only
                      The converted quadword.
  
     QWORD            Reference   I*8           Input only
                      The quadword to be converted.
2 ICR_QUAD_TO_F
 
                     RESULT = ICR_QUAD_TO_F(QWORD)

 This function converts  a  quadword  integer  to  a  single  precision
 floating  point  number.   Note  that  precision  will be lost in this
 conversion as floating point has only 24 bits of precision.
3 Calling_sequence
 
                     RESULT = ICR_QUAD_TO_F(QWORD)

     Name             Mechanism   Type          I/O
                      Description
  
     RESULT                       F*4           Output only
                      The converted quadword.
  
     QWORD            Reference   I*8           Input only
                      The quadword to be converted.
2 ICR_REMOVE_FRONT
 
               ICR_REMOVE_FRONT(LENGTH,STRING,STRING_LEN)

 Removes characters from the front a string  and  updates  the  current
 trimmed length of the string.
3 Calling_sequence
 
               ICR_REMOVE_FRONT(LENGTH,STRING,STRING_LEN)

     Name             Mechanism   Type          I/O
                      Description
  
     LENGTH           Reference   I*4           Input only
                      Number of characters to be removed from the front
                      of the string.
  
     STRING           Descriptor  S*(*)         Input/output
                      String from which characters are to be removed.
  
     STRING_LEN       Reference   I*4           Input/output
                      Current trimmed length of string.
2 ICR_SCAN
 
         LOCATION = ICR_SCAN(STRING,SCAN_STRING,START_LOCATION)

 Scans STRING starting at START_LOCATION,  returns  location  of  first
 character in STRING which isn't in SCAN_STRING.
3 Calling_sequence
 
         LOCATION = ICR_SCAN(STRING,SCAN_STRING,START_LOCATION)

     Name             Mechanism   Type          I/O
                      Description
  
     LOCATION                     I*4           Output only
                      Location of first character in STRING which isn't
                      in              SCAN_STRING.               Equals
                      MAX(START_LOCATION,LEN(STRING)+1) if whole STRING
                      is scanned.
  
     STRING           Descriptor  S**           Input only
                      Character variable to be scanned.
  
     SCAN_STRING      Descriptor  S**           Input only
                      Character variable containing  characters  to  be
                      scanned over.
  
     START_LOCATION   Reference   I*4           Input only
                      Position in STRING at which to begin scanning.
2 ICR_$SEARCH
 
                 STATUS = ICR_$SEARCH(RESULTANT_STRING)

 This function is an interface to the RMS $SEARCH  macro.   It  may  be
 used after calling ICR_$PARSE to fill in the file identification field
 in the NAM block and  to  fully  resolve  the  resultant  string  file
 specification.   ICR_$SEARCH  may  be called repeatedly until RMS$_NMF
 (no more  files)  is  returned  to  get  all  files  which  match  the
 "file_name" parameter of ICR_$PARSE, which may include wild cards.
3 Calling_sequence
 
                 STATUS = ICR_$SEARCH(RESULTANT_STRING)

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code.
  
     RESULTANT_STRING Descriptor  S**           Output only
                      This  string  receives  the  file   specification
                      resulting  from  the  resolution  of  all  system
                      defaults, including version numbers and wild card
                      character substitutions.
2 ICR_SET_SWITCHES
 
    STATUS = ICR_SET_SWITCHES(SWITCH_1,MASK_1[,SWITCH_2,MASK_2 ...])

 Makes a set  of  switches  known  to  the  switch  parser  ICR_SWITCH.
 ICR_SWITCH  will  return  the  corresponding  MASK_i  if  SWITCH_i  is
 encountered when parsing a switch.  Type HELP ICR ICR_SWITCH for  more
 information.
3 Calling_sequence
 
    STATUS = ICR_SET_SWITCHES(SWITCH_1,MASK_1[,SWITCH_2,MASK_2 ...])

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code.
  
     SWITCH_i         Descriptor  S**           Input only
                      String (without a '/') containing  switch  to  be
                      recognized (e.g.  'LIST' to match '/LIST').
  
     MASK_i           Reference   I*4           Input only
                      Value to be returned by ICR_SWITCH if SWITCH_i is
                      encountered..   The  value  must  not be negative
                      since ICR_SWITCH returns a  negative  mask  if  a
                      switch with arguments is parsed.
2 ICR_STDESCR
 
          STR_DESC = ICR_STDESCR(%DESCR(BYTE_ARRAY)[,LENGTH])

 Return a standard string descriptor given an array descriptor.  May be
 used  to  pass  Fortran  byte  arrays  to routines expecting character
 variables.
3 Calling_sequence
 
          STR_DESC = ICR_STDESCR(%DESCR(BYTE_ARRAY)[,LENGTH])

     Name             Mechanism   Type          I/O
                      Description
  
     STR_DESC                     F*8           Output only
                      Standard VAX/VMS string descriptor.
  
     BYTE_ARRAY       Descriptor  I*1(*)        Input only
                      Byte array of characters.
  
     LENGTH           Reference   I*4           Input only
                      Optional string length.
2 ICR_STRIP_FRONT
 
                ICR_STRIP_FRONT(STRIP,STRING,STRING_LEN)

 Strips any characters contained in strip from the front of string  and
 left justifies string.
3 Calling_sequence
 
                ICR_STRIP_FRONT(STRIP,STRING,STRING_LEN)

     Name             Mechanism   Type          I/O
                      Description
  
     STRIP            Descriptor  S*(*)         Input only
                      String containing any characters to  be  stripped
                      from the front of the string.
  
     STRING           Descriptor  S*(*)         Input/output
                      String  from  which  the  characters  are  to  be
                      stripped.
  
     STRING_LEN       Reference   I*4           Input/output
                      Current trimmed length of string.
2 ICR_SUBQUAD
 
                           ICR_SUBQUAD(A,B,C)

 This procedure subtracts two  quadword  integers  ('A'  abd  'B')  and
 returns the difference in 'C'.
3 Calling_sequence
 
                           ICR_SUBQUAD(A,B,C)

     Name             Mechanism   Type          I/O
                      Description
  
     A                Reference   I*8           Input only
  
     B                Reference   I*8           Input only
  
     C                Reference   I*8           Output only
                      Resultant quadword.
2 ICR_SWITCH
 
    STATUS = ICR_SWITCH(STRING,SWITCH_STRING,SWITCH_LEN,SWITCH_MASK)

 ICR_SWITCH is a generalized switch parser for VAX/VMS qualifiers.   It
 will  recognize  any  valid  VMS  qualifier.   It  may  be tailored to
 recognize  a  particular  set  of   qualifiers   using   the   routine
 ICR_SET_SWITCHES.    Type   HELP   ICR   ICR_SET_SWITCHES   for   more
 information.
3 Calling_sequence
 
    STATUS = ICR_SWITCH(STRING,SWITCH_STRING,SWITCH_LEN,SWITCH_MASK)

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status  code.   Status  will  be
                      true  if  a  switch  was  encountered  and  false
                      otherwise.
  
     STRING           Descriptor  S**           Input only
                      String containing the switch to be  parsed.   The
                      string  must  be left justified with a '/' as the
                      first character.
  
     SWITCH_STRING    Descriptor  S**           Output only
                      String to receive the switch  being  parsed.   It
                      must  be  large  enough  to  contain  the longest
                      switch to be parsed.
  
     SWITCH_LEN       Reference   I*4           Output only
                      The  length  (without  trailing  blanks)  of  the
                      switch returned in SWITCH_STRING.
  
     SWITCH_MASK      Reference   I*4           Output only
                      If the matched switch is one of  those  specified
                      in  a call to ICR_SET_SWITCHES, the corresponding
                      mask value will be returned.  Otherwise a 0  will
                      be  returned.   In  either  case,  if  the switch
                      contained arguments, a 80000000 hex will be  ored
                      with    the    mask   value.    Type   HELP   ICR
                      ICR_SET_SWITCHES for more information.
2 ICR_TRNLOG_STR
 
             STATUS = ICR_TRNLOG_STR(LOG_STRING,TRN_STRING)

 Fully translate a logical name.  log_string and trn_string may be  the
 same string variable.
3 Calling_sequence
 
             STATUS = ICR_TRNLOG_STR(LOG_STRING,TRN_STRING)

     Name             Mechanism   Type          I/O
                      Description
  
     STATUS                       I*4           Output only
                      Standard VAX/VMS status code.
  
     LOG_STRING       Descriptor  S**           Input only
                      Logical name string to be translated.
  
     TRN_STRING       Descriptor  S**           Output only
                      Fully translated logical name equivalent.
