M432 Utility Routines for Character String Parsing and Construction

The routines of this package analyse and manipulate Fortran CHARACTER strings.

Structure:

SUBROUTINE and FUNCTION subprograms
User Entry Names:

CKRACK,	CCOPYL,	CCOPYR,	CCOPIV,	CCOSUB,	CENVIR,	CFILL,	CLEFT,
CRIGHT,	CSQMBL,	CSQMCH,	CLTOU,	CUTOL,	CSETDI,	CSETHI,	CSETOI,
CSETVI,	CSETVM,	CTRANS,	ICDECI,	ICHEXI,	ICOCTI,	ICEQU,	ICFIND,
ICFILA,	ICFMUL,	ICFNBL,	ICLOC,	ICLOCL,	ICLOCU,	ICLUNS,	ICNEXT,
ICNTH,	ICNTHL,	ICNTHU,	ICINQ,	ICINQL,	ICINQU,	ICNUM,	ICNUMA,
ICNUMU,	ICTYPE,	LNBLNK,	NCDECI,	NCHEXI,	NCOCTI

COMMON Block Names and Lengths: /SLATE/ 40
Summary:

CALL CKRACK	Read integer or real number from character
CALL CCOPYL	Copy string, left shift allowed if overlap
CALL CCOPYR	Copy string, right shift allowed if overlap
CALL CCOPIV	Copy string, with characters front-to-back
CALL CCOSUB	Copy string, replacing a token by text
CALL CENVIR	Copy string, replacing environment variables
CALL CFILL	Fill
CALL CLEFT	Left justify
CALL CRIGHT	Right justify
CALL CSQMBL	Squeeze multiple blanks
CALL CSQMCH	Squeeze multiple character
CALL CLTOU	Convert low to up
CALL CUTOL	Convert up to low
CALL CSETDI	Set decimal integer to character
CALL CSETHI	Set hexadecimal integer to character
CALL CSETOI	Set octal integer to character
CALL CSETVI	Set a vector of integers to character
CALL CSETVM	Set a series of generated integers to character
CALL CTRANS	Character translation
IX = ICDECI	Read decimal integer from character
IX = ICHEXI	Read hexadecimal integer from character
IX = ICOCTI	Read octal integer from character
IX = ICEQU	Compare two strings for equality
JX = ICFIND	Find first occurrence, single
JX = ICFILA	Find last occurrence, single
JX = ICFMUL	Find first occurrence, multiple
JX = ICFNBL	Find first non-blank

continue:

JX = ICLOC	Locate case sensitive
JX = ICLOCL	Locate case insensitive, up to low
JX = ICLOCU	Locate case insensitive, low to up
JX = ICLUNS	Locate unseen characters
JX = ICNEXT	Delimit next word
JX = ICNTH	Identify choice case sensitive
JX = ICNTHL	Identify choice case insensitive, up to low
JX = ICNTHU	Identify choice case insensitive, low to up
JX = ICINQ	Inquire presence in a list, case sensitive
JX = ICINQL	Inquire presence in a list, case insensitive, up to low
JX = ICINQU	Inquire presence in a list, case insensitive, low to up
JX = ICNUM	Verify numeric
JX = ICNUMA	Verify alpha-numeric
JX = ICNUMU	Verify alpha-numeric or underscore
JX = ICTYPE	Identify type
NX = LNBLNK	Find last non-blank character
IX = NCDECI	Read decimal integer from character
IX = NCHEXI	Read hexadecimal integer from character
IX = NCOCTI	Read octal integer from character

Usage:

General Remarks:
For what follows, let the CHARACTER variable LINE contain a string of n characters assuming the following declaration:

       CHARACTER LINE*(n),COL(n)*1
       EQUIVALENCE(LINE,COL)

    COMMON /SLATE/ ND,NE,NF,NG,NUM(2),DUMMY(34)

The types of all variables and functions follow from the Fortran default typing convention, except that LINE, COL, and variables starting with the letters CH are of type CHARACTER.
Convention
Typing rules for data to be interpreted by CKRACK:

Binary:

String of zeros or ones prefixed by #B or #b.

Octal:

String of octal digits prefixed by #0 or #O or #o.

Hex:

String of hexadecimal digits prefixed by #X or #x.

Integer:

String of decimal digits optionally prefixed by + or -.

Real:

[+|-] [int] [.] [fract] [E] [+|-] [exp]
int, fract, exp are strings of decimal digits, either the decimal dot or the letter E (or e) must be present.

Double:

[+|-] [int] [.] [fract] D [+|-] [exp]
the letter D (or d) must be present.

Read integer or real number from character:

    CALL CKRACK(LINE,JL,JR,IFLD)

CKRACK detects the type of the number (bit-pattern, integer, real single, real double) from its representation. The typing rules for data to be interpreted by CKRACK are given in the note on the previous page.

The number read is returned in /SLATE/ in NUM(1) or ANUM(1) or DNUM, for which one will need:

    REAL ANUM(2)
    DOUBLE PRECISION DNUM
    EQUIVALENCE (ANUM(1),NUM(1)),(DNUM,NUM(1))

The flag in the last parameter is normally given as zero; $IFLD\; >\; 0$ demands that single-precision real numbers be handled and returned as double precision numbers; demands that double-precision numbers be returned in single precision.

Apart from NUM, the following parameters are returned in /SLATE/:

ND

Number of numeric digits seen.

COL(NE)

Terminating character in the field; $NE=JR+1$ if terminated by end-of-field.

NF

Type of the number read:
error code for bad data;
$=0:$ the whole field is blank;
$=1:$ bit pattern (binary, octal, or hexadecimal);
$=2:$ integer
$=3:$ single precision real;
$=4:$ double precision real.

NG

$=0$ for normal termination; special termination otherwise.

    CALL CCOPYL (CHFROM,CHTO,NCH)

    CALL CCOPYR (CHFROM,CHTO,NCH)

    CALL CCOPIV(CHFROM,CHTO,NCH)

Copy string, replacing a token by text:

    CALL CCOSUB(CHFROM,NFR,LINE,JL,JR,CHTOKEN,CHSUB)

The following parameters are returned in /SLATE/:

ND

Number of characters stored;

COL(NE)

is the first character after the last stored;

NF

Non-zero if LINE(JL:JR) too small to receive the complete copy;

NG

Zero if no substitution was done, i.e. CHTOKEN did not occur.

    CALL CENVIR(CHFROM,NFR,LINE,JL,JR,IFLAG)

The following parameters are returned in /SLATE/:

ND

Number of characters stored;

COL(NE)

is the first character after the last stored;

NF

Bit 1 is set if undefined env/v have been encountered;

Bit 2 is set if syntax error (missing closing bracket);

Bit 3 is set if LINE(JL:JR) is too small to receive the copy;

NG

Zero if no substitution was done.

    CALL CFILL(CHI,LINE,JL,JR)

    CALL CLEFT(LINE,JL,JR)

ND

Number of non-blank characters in the field.

COL(NE)

First blank character after left-justifying (or $NE=JR+1$ if there are no blanks).

    CALL CRIGHT(LINE,JL,JR)

ND

Number of non-blank characters in the field.

COL(NE)

Last blank character after right-justifying (or $NE=JL-1$ if there are no blanks).

Squeeze multiple blanks:

    CALL CSQMBL(LINE,JL,JR)

ND

Number of characters retained (vacated trailing characters, if any, are blanked).

COL(NE)

First blank character after (or $NE=JR+1$ if there are no multiple blanks).

    CALL CSQMCH(CHIS,LINE,JL,JR)

ND

Number of characters retained (vacated trailing characters, if any, are blanked).

COL(NE)

First character after the squeezed string (or $NE=JR+1$ if there are no multiple occurrences).

    CALL CLTOU(LINE(JL:JR))

    CALL CUTOL(LINE(JL:JR))

    CALL CSETDI(INT,LINE,JL,JR)

ND

Number of digits which have been set.

COL(NE+1)

Most significant digit set.

COL(NF+1)

Most significant character set. $NF=NE$ if INT is positive, $NF=NE-1$ if INT is negative and no overflow.

NG

$=0$ normally, non-zero if field too small.

    CALL CSETHI(INT,LINE,JL,JR)

    CALL CSETOI(INT,LINE,JL,JR)

Set a vector of integers to character:

    CALL CSETVI(NI,INTV,NBIAS,LINE,JL,JR,NCOL,IFLSQ)

COL(NE)

Last character of the last integer stored.

NG

$=0$ normally, $=N>0$ if there is not enough room to store INTV(N).

    CALL CSETVM(NI,INC,IGO,LINE,JL,JR,NCOL,IFLSQ)

    CALL CTRANS(CHO,CHN,LINE,JL,JR)

    IX = ICDECI(LINE,JL,JR)

ND

Number of digits read ( '-' or '+' do not count).

COL(NE)

Terminating character in the field; $NE=JR+1$ if pure numeric or if the whole field is blank (in which case $ND=0$ ).

NG

$=0$ if the number is terminated by 'blank' or by end-of-field, non-zero otherwise.

    IX = ICHEXI(LINE,JL,JR)

    IX = ICOCTI(LINE,JL,JR)

    IX = ICEQU(CHA,CHB,N)

Note: this and many other routines of this package are handy when manipulating text stored in an area declared with CHARACTER TEXT(big)*1, which will explain some of the maybe unexpected calling sequences.

Find first occurrence, single:

    JX = ICFIND(CHIS,LINE,JL,JR)

JX

$=JR+1$ if CHIS is not contained in LINE(JL:JR), or if $JL\; >\; JR$ .

NG

$=0$ if not found, $=JX$ otherwise.

    JX = ICFILA(CHIS,LINE,JL,JR)

JX

$=JR+1$ if CHIS is not contained in LINE(JL:JR), or if $JL\; >\; JR$ .

NG

$=0$ if not found, $=JX$ otherwise.

    JX = ICFMUL(CHI,LINE,JL,JR)

JX

$=JR+1$ if none of CHI is found in LINE(JL:JR), or if $JL\; >\; JR$ .

ND

=j, i.e. COL(JX) is CHI(j:j) if found.

NG

$=0$ if not found, $=\; JX$ otherwise.

    JX = ICFNBL(LINE,JL,JR)

JX

$=JR+1$ if LINE(JL:JR) is all blank, or if $JL\; >\; JR$ .

NG

$=0$ if all blank, $=\; JX$ otherwise.

    JX = ICLOC(CHI,NI,LINE,JL,JR)

    JX = ICLOCL(CHI,NI,LINE,JL,JR)

    JX = ICLOCU(CHI,NI,LINE,JL,JR)

    JX = ICLUNS(LINE,JL,JR)

Delimit next word:

    JX = ICNEXT(LINE,JL,JR)

JX

Position of the first character of the 'word'.

NE

Position of the first 'blank' after the 'word' or $NE=JR+1$ .

ND

Number of characters in the 'word'.
$JX=NE=JR+1$ , $ND=0$ if LINE(JL:JR) is all blank.

    JX = ICNTH(CHACT,CHPOSS,NPOSS)

To allow matching a shortened key-word given in CHACT one may insert ( la VAX) a '*' in the text of CHPOSS(J) to mark the separation between the obligatory and further possible characters; a second '*' may be given to signal that CHACT may have any other characters beyond this point, this is implied if the string in CHPOSS(J) is not blank terminated.
For example:

    PARAMETER  (NPOSS=6)
    CHARACTER*8 CHPOSS(NPOSS)
    DATA CHPOSS /'del*ete ', 'add     ', 'adb*efor',
   +             'rep*lace', 'ch*ange ', 'c*ol*   '/

     CHACT = 'add'       JX = 2   exact match
             'delete'         1   exact match
             'del'            1   short match
             'del  '          1
             'delphi'         0   wrong optional characters
             'deleted'        0   CHPOSS(1) is terminated
             'replaced'       4   CHPOSS(4) is not terminated
             'chan'           5   short match
             'channel'        0   wrong optional characters
             'c'              6   short match
             'columns'        6   abritrary trailing characters allowed
             'cols'           6

    JX = ICNTHL(CHACT,CHPOSS,NPOSS)

    JX = ICNTHU(CHACT,CHPOSS,NPOSS)

Inquire presence in a list, case sensitive:

    JX = ICINQ(CHLOOK,CHHAVE,NHAVE)

As opposed to ICNTH, a '*' may be given in CHLOOK, but not in CHHAVE(J), to allow wild-card checking on the presence of a string in the list of CHHAVE(J). The '*' divides the string into the characters which must be present in the looked-for object of CHHAVE(J), and additional restricting characters which can be absent, but if present they must be right. Again a second '*' can be given in CHLOOK, but this is not useful, since any characters beyond the string terminator both in CHLOOK and in CHHAVE(J) are assumed to be allowed anyway, unlike as with ICNTH.

For example:

    PARAMETER  (NHAVE=7)
    CHARACTER*8 CHHAVE(NHAVE)
    DATA CHHAVE /'apo     ', 'apol    ', 'apollo  ', 'irs6000 ',
   +             'decra1  ', 'decra2  ', 'decra3  '/

    CHLOOK = 'apo'       JX = 1
             'apo*'           1
             'ap*ollo'        1
             'ap*'            1
             'ap'             0
             'apol'           2
             'apoll'          0
             'apoll*'         3
             'ir*s60'         4
             'ir*s70'         0
             'dec*'           5
             'dec*ra'         5
             'dec*ra*'        5
             'dec*ra3'        7

With ICNTH we have a key word CHACT which we try to identify; CHPOSS(N) is most likely a fixed table built into the program which gives the possible key words and allowed abbreviations à la VAX. The return value from ICNTH tells us which key word we have.

With ICINQ we inspect a table CHHAVE(N), which most likely has been built up at execution time, to see whether it contains an object according to the specifications given in CHLOOK. The interesting thing about the return value from ICINQ is mainly whether it is zero or not, the position of the found object in the table is of secondary importance.
Inquire presence in a list, case insensitive, up to low:

    JX = ICINQL(CHLOOK,CHHAVE,NHAVE)

Inquire presence in a list, case insensitive, low to up:

    JX = ICINQU(CHLOOK,CHHAVE,NHAVE)

    JX = ICNUM(LINE,JL,JR)

JX

$=JR+1$ if LINE(JL:JR) is all numeric.

ND

Number of digits seen in LINE(JL:JX-1).

NG

$=0$ if all numeric, $=JX$ otherwise.

    JX = ICNUMA(LINE,JL,JR)

JX

$=JR+1$ if LINE(JL:JR) is all alpha-numeric.

ND

Number of alpha-numeric characters seen in LINE(JL:JX-1).

NE

Position of the first numeric character, $=0$ if none.

NF

Position of the first alphabetic character, $=0$ if none.

NG

$=0$ if all alpha-numeric, $=\; JX$ otherwise.

    JX = ICNUMU(LINE,JL,JR)

    JX = ICTYPE(CHIS)

JX

$=\; 0:$ Unseen, i.e. a character not showing on an ASCII terminal.
$=\; 1:$ Anything else.
$=\; 2:$ Numeric character.
$=\; 3:$ Lower case character.
$=\; 4:$ Upper case character.

    NX = LNBLNK(CHV)

Read decimal integer from character:

    IX = NCDECI(CHTEXT)

    IX = NCHEXI(CHTEXT)

    IX = NCOCTI(CHTEXT)

M433