EDITFST(1)

RPN UTILITY

EDITFST(1)

NAME

editfst version 3.0 (March 92)
editfst2000 version 5.8+ (July 2001)

USAGE

editfst [-s -d -sseq -dseq -i -l -e -v -vs -vd -c -nrecmin -k -m -n]

Examples of usage:
  • editfst
  • editfst -s input1 input2 input3 -d output0 -i command.dir -l out_list
  • editfst -s infile0 -d outfile0 -sseq -dseq
  • editfst2000 -s aaa bbb -d ccc -i cmd.dir

    DESCRIPTION

    Utility used for editing and copying records from RPN standard files into a new or an existing RPN standard file. It can do a straight (complete) copy of the input file or it can copy records selectively as indicated from the standard input or from a file of directives named in the "-i" key.


    Definitions of keys in the command line
    keydescription
    -s srcfile
    -s filea fileb filec    		 one or multiple (up to 35) names of the input files; For the rest of the documentation, "srcfiles" will be referred as the files defined in here. Source files can also be defined in the STDCOPI in the stdin directives
    -d dstfilename of the destination (resulting/output) file; For the rest of the documentation, "dstfile" will be referred as the file defined in here. Destination files can also be defined in the STDCOPI in the stdin directives
    -sseqindicates that the srcfiles is of type SEQuential
    -dseqindicates that the dstfile is of type SEQuential
    -i 0

    -i edit.dir
  • a "0" means to concatenate all the srcfiles into the dstfile.
  • If key is omitted, this means utility expects directives from stdin.
  • If the key is given a name of the file, the utility will act on the directives stored in this file.
    (The directives given to the utility controls the selective copying from the source files to the destination file. These directives are documented in a table below.)
    • -l listingfile given for the stdout listing
    -e A 'RND' record will be over-written if its search descriptors NOM,TYPE,IP1,IP2, IP3,ETIKET (except DATE) are identical to the ones of the record to be copied
    -vverbose mode, indicates which records are added to the dstfile like the format utility voir
    -vsprints the table of contents of the srcfiles like the format utility voir
    -vdprints the table of contents of the dstfile like the format utility voir
    -c 100maximum number of records to be copied to the dstfile
    -nrecmin 100minimum number of records expected to be copied to the dstfile. If the number of records copied are less than this value, a non-zero status code will be returned, otherwise, it will return "0" (normal status code)
    -k fataleminimum error level to abort: 'fatale' or 'errors'
    -m informmessage level: either 'inform' or 'errors' or 'debugs'
    -nOutputs no boxes around the message EXDB, EXFIN, at the beginning and at the end of the execution respectively.

    Description of Directives
  • Directives must not start on the first column. (a "C" on the first colum indicates that it is commented out)
  • Directives are implemented in sequential order so some will affect subsequent commands!
    • Directives Description and Usage
    DESIRE DESIRE(TYPVAR,NOMVAR,ETIKET,DATE,IP1, IP2,IP3)
    Copies (desires) the records that meet the 7 selection parameters:
  • Examples of usage:
    desire(-1,-1,-1,-1,-1,-1,-1)
    desire('A','TT','REGIONAL',100185000,12000,6,0)
    desire('P',['UU','VV'], -1 ,-1 ,[1000.,750.],[0,12,18,24],-1)
    desire(['A','P'],'PN',-1,[100185000,@,100685120,DELTA,6],-1,-1,-1)
    desire(-1,'TT','GLOBAL',COMMUNE,-1,0,0)
    desire(-1,-1,-1,-1,[1.0,SIGMA],-1,-1)

  • TYPVAR: type of variable; 'A'(analysis),'P'(forecast),'X'
  • NOMVAR: variable name
  • ETIKET: label recorded from the original model run
  • DATE: CMC date timestamp,if the keyword COMMUNE is used, it will be controlled by the directive "PERIODE"
  • IP1: the level of the field (in pressure,eta,metres,other)
  • IP2: the hour of the forecast (rounded off if not exact)
  • IP3: value of 0 unless otherwise modified
    NOTE: If one wants to use supplementary selection parameters such as NI,NJ,NK,IG1,IG2,IG3,IG4,GRTYP, see the command CRITSUP below

    The selection parameters can be defined in these 3 forms.
    (1) The universal key (-1) means no selection criteria for this parameter
    (2) One value, integer or a character string surrounded by quotes
    (3) A list of up to 10 elements in this form [?,?,?]

  • For DATE,IP1,IP2,IP3, it can also be given a range with a starting and ending integer in the following form: [start,@,end], and intervals can be added with the keyword 'DELTA' in the form [start,@,end,DELTA,interval]
    Examples for DATE:
    Always use 'r.date' to see the actual date from the encoded timestamp. a) [299823200,@,299888000,DELTA,6]
    From May 22,2002,00Z to May 25,2002, 00Z (inclusive) every 6 hours
    b) [299969000,@]
    From May 28,2002,18Z(included) and on.
    c) [@,299855600]
    Anything before and including May 23,2002, 12Z.
    Examples for IP2:
    d) [@,120]
    All values up to 120 (hours)
    e) [12,@,48,DELTA,12]
    From hour 12 to hour 48, every 12 hours
    Examples for IP1:
    f) [@,12000]
    Anything up to 12000 for IP1 values
    g) [50,@,1000,DELTA,50]
    All values starting at 50mb up to 1000mb, every 50mb

  • In addition, for IP1 only, (editfst2000 -recommend revision 5.84 or higher), it can be defined with a level type and a level value in a pair form: [real value, level type] The level types recognized are:
    SIGMA (values from 0.0 to 1.0)
    MBAR (millibars)
    METERS(metres)
    OTHER
    HYBRID(values from 0.0 to 1.0)(revision 5.84 or higher)

    Examples:
    a) [100.,MBAR,750.,MBAR,1000.,MBAR]
    100 mb, 750 mb, 1000 mb
    b) [100.,MBAR,@,750.,MBAR,DELTA,50.,MBAR]
    From 100 mb to 750 mb,every 50mb
    c) [@,750.,MBAR]
    anything lower and up to 750 mb
    c) [.859,SIGMA,1.0,SIGMA]
    sigma levels at 10590 and 12000 only

    NOTE: if both "DESIRE" and "EXCLURE" are not used, it will copy all srcfiles into the dstfile. The search of records to copy is done throughout the entire "random access" file or, from the current position of a "sequential" file. When there are fewer than 7 parameters defined, the last missing parameters are set to "-1".
    • EXCLURE EXCLURE(TYPVAR,NOMVAR,ETIKET, DATE,IP1, IP2,IP3)
    Excludes the records that meet the 7 selection parameters.
  • Examples of usage:
    exclure(A,TT,'REGIONAL',299823200,12000,6,0)
  • See above in "DESIRE" for the description of the parameters. Note that this command should be used before "DESIRE" as the directives are implemented in sequential order
    • CRITSUP CRITSUP(NI,NJ,NK,GRTYP, IG1,IG2,IG3,IG4)
    1 to 8 supplementary selection parameters that can be used with the DESIRE and EXCLURE directives.(This command only affects future calls to DESIRE/EXCLURE.)
  • Examples of usage:
    critsup(400,200,-1,'G',-1,-1,-1,-1)
    exclure('A',-1,-1,-1,-1,-1,-1)
    desire(-1,['UU','VV'],-1,-1,-1,-1,-1)
    critsup(-1)
    desire(-1,'TT',-1,-1,-1,-1,-1)
  • NI: number of points along I
  • NJ: number of points along J
  • NK: number of points along K
  • IG1: grid descriptor 1
  • IG2: grid descriptor 2
  • IG3: grid descriptor 3
  • IG4: grid descriptor 4
  • GRTYP: grid type ('E','G','L',etc.)
    The selection parameters can be defined in these 2 forms.
    (1) The universal key (-1) means no selection criteria for this parameter
    (2) One value, integer or for GRTYP, one character string surrounded by quotes
    The "critsup (-1)" will negate the previous "critsup" command for the EXCLURE/DESIRE commands that follow afterwards.
    • ZAP ZAP(TYPVAR,NOMVAR,ETIKET,DATE, IP1,IP2,IP3)
    Modifies the record parameters during the copy by replacing with the values given in the arguments of this directive.
  • Only one value can be given per argument as this is NOT a selection criteria. If the value is -1, no modification will be done for that argument. If several ZAP commands appear, only the last one is applicable. Use STDCOPI if one wants to use several sets of a selection and modificationZAP commands
  • Examples of usage:
    desire(-1,'TT',-1,-1,-1,-1,-1)
    zap('A',-1,'GLBANAL',-1,-1,-1,-1)
    (The example above selects all 'TT' records and then replaces in each of these selected records, the typvar with 'A' and the etiket with 'GLBANAL'.

    zap (-1,-1,'HELLO' ,-1,-1,-1,-1)
    desire (-1,'UU',-1,-1,-1,-1,-1)
    stdcopi (-1)
    zap ('A',-1,'GOODBYE',-1,-1,-1,-1)
    desire (-1,'TT',-1,-1,-1,-1,-1)
    stdcopi (-1)
    (The example above selects all 'UU' records and then replaces in each of these selected records, the etiket with 'HELLO' and writes it out. Then it selects all the TT records and then writes them out and replaces the typvar with 'A' and the etiket with 'GOODBYE' at the same time.)
    NOTE: When some parameters are missing, the value of -1 is the default.
    • PERIODE PERIODE(DN, ECART, DUREE, DELTA)
    Sets a common date or time period for the following DESIRE and EXCLURE directives when 'COMMUNE' is used in the argument of DATE. This should be called before DESIRE/EXCLURE.
  • Examples of usage:
    PERIODE('OPRUN',6,240,6)
    desire(-1,'TT','GLOBAL',COMMUNE,-1,0,0)
    PERIODE(9930000,6,24,1)
    desire(-1,'UU','GLOBAL',COMMUNE,-1,0,0)
    PERIODE(-299823200,0,12,3)
    desire(-1,'VV','GLOBAL',COMMUNE,-1,0,0)
    PERIODE(#, 0, 0, 1)
    desire(-1,'WW','GLOBAL',COMMUNE,-1,0,0)
  • DN: Argument used to call IOPDATM.
    It may take one of the following forms:
    'OPRUN'- operationnal run date
    YYJJJZZ - a positive number; year,julian day,zulu hr
    -CMCSTAMP - a negative integer; CMC date timestamp (-299823200).
  • ECART: Number of hours added to the date received from IOPDATM to obtain the beginning of the period
  • DUREE: Duration of the period in hours from the start of the period
  • DELTA: The interval in hours desired from the start of the period NOTE: Omitted arguments get their default value.
    • DEBUG DEBUG=OUI/NON [ NON ]
    OUI: Same meaning as the "-m debugs" key.
    NON: Cancels the effect of a "DEBUG=OUI" directive or of a "-m" key.
    DIAG DIAG=OUI/NON [ NON ]
    OUI: Same meaning as the "-m inform" key.
    NON: Cancels the effect of a "DIAG=OUI" directive of of the "-m" key.
    ECR ECR=OUI/NON[ NON ]
    OUI: Same meaning as the "-e" key.
    NON: Cancels the effect of a "ECR=OUI" directive or that of the "-e" key.
    LIMITE LIMITE = N [ -1 ]
    N > 0 Copy up to N number of records into the dstfile.
    N < 0 Copy unlimited number of records into the dstfile.
    Same as the "-c" key
    VOIRD VOIRD = OUI/NON [ NON ]
    OUI: Same meaning as the "-vd" key.
    NON: Cancels the effect of a "VOIRD=OUI" directive or of a "-vd" key.
    VOIRS VOIRS = OUI/NON [ NON ]
    OUI: Same meaning as the "-vs" key.
    NON: Cancels the effect of a "VOIRS=OUI" directive or of a "-vs" key.
    FIXDATE FIXDATE = OUI/NON [ NON ]
    OUI: Indicates that the date of the first record is valid for all the records in the srcfiles.
    NON: Indicates to check the date for each record in the srcfiles.
    SAUVDES SAUVDES = N [ O ] Controls the validity of the directives DESIRE or EXCLURE after copy.
  • N =-1 The DESIRE/EXCLURE directives stay valid.
  • N > 0 The first N DESIRE/EXCLURE directives stay valid.
  • N = 0 The DESIRE/EXCLURE directives become invalid.
    • REWINDS REWINDS(SFILE) [#]
  • Examples of usage:
    REWINDS('SEQFILE')
    • Opens the sequential file 'SFILE' and goes to the beginning.
  • SFILE: Name of the file to be rewound (string surrounded by quotes)
    • STDCOPI STDCOPI(SFILE,TYPS,DFILE,TYPD) [#, -1, -1, -1]
  • Examples of usage:
    STDCOPI('SX', 'RND', 'yyy', 'RND')
    STDCOPI('SY', 'SEQ')
    STDCOPI('SZ')
  • Other examples: look at ZAP
    • Copies, in the conditions set by the previous directives, a selection of input file records to the output file.
  • SFILE: Input filename (character string with quotes)
  • TYPS: Type of the input file: 'RND' or 'SEQ'
  • DFILE: Output filename
  • TYPD: Type of the output file: 'RND', 'SEQ'
    NOTES:
    a) STDCOPI can change the input and output files on the fly.
    b) The names and type of files don't change if:
    -they have an actual value of -1
    -unspecified (argument list abbreviated)
    c)If the input file is sequential, the record search is done starting from its current position.
    d)If the output file is sequential, EDITFST writes to it from its current position.
    e)This command behaves correctly for editfst2000 from versions editfst_5.85 and up only. It is correct for editfst
    The examples given are used to add the contents from files 'SX'(RND), 'SY'(SEQ) and 'SZ'(SEQ) to the file 'yyy'(RND)

    • LAST UPDATE OF DOCUMENTATION

    Nov 20th, 2002, by Vivian Lee