; must = parse | search | display | open_u | open_r | open_w | open_rw | map
;
;     r2 = addr of fip
;     r3 = argm mask
;
;============================
; checks the fip$a_fip parameter.  if it exists, it moves the address of that
; fip to r2 to be worked with by the rest of the routines.  If the address is
; 0, then it calls fip$alofip to allocate a new fip, leaving its address in
; both r2 and the argument variable.
      .MACRO $CHECK_FIP, arg=<1>, reg=<r2>, err, ?label1
         moval fip$al_fip0, reg               ; default = FIP0
         bbc   #arg, r3, label1               ; if not given, skip rest
         movl  @<arg*4>(ap), reg              ; r2 = addr of fip
         bneq  label1
         jsb   fip_alofip                    ; if fip=0, ALOFIP
         .iif nb <err>, $onerr err            ; if err given, onerr goto err
         movl  r2, @<arg*4>(ap)               ; return addr in arg
label1:
         movl #1, fip$f_status(r2)            ; init status value
      .ENDM
;============================
; to check for fip$a_file parameter.  if it exists, and is nonzero, jsb to
; fip_parse.  if zero, jsb to fip_search.
      .MACRO $CHECK_FILE, err, ?search, ?parse, ?egress
         bbc  #fip$a_file, r3, egress
         movaq  @fip$p_file(ap), r1
         tstl   4(r1)
         bneq   parse
search:
         jsb    fip_search
         brb    egress
parse:
         jsb    fip_parse
egress:
      .ENDM
;============================
; just to check that args to $prepare_file are valid.
      .MACRO $VERIFY_MUST_VALUES, must
         .irp cond, <must>
            $verify_must_value cond
         .endr
      .ENDM
;----------
      .MACRO $VERIFY_MUST_VALUE, must_be
         .iif idn <must_be>, <close>,   .mexit    ; mapped, ufo
         .iif idn <must_be>, <map>,     .mexit    ; mapped, ufo
         .iif idn <must_be>, <open_rw>, .mexit    ; $opened fop=put,get?
         .iif idn <must_be>, <open_w>,  .mexit    ; $opened fop=put
         .iif idn <must_be>, <open_r>,  .mexit    ; $opened fop=get
         .iif idn <must_be>, <open_u>,  .mexit    ; $opened fop=ufo
         .iif idn <must_be>, <display>, .mexit    ; $displayed or $opened
         .iif idn <must_be>, <search>,  .mexit    ; $searched
         .iif idn <must_be>, <parse>,   .mexit    ; $parsed
         .error 0; illegal MUST condition: "must_be"
      .ENDM
;============================
; to make sure certain operations have been performed on a file, performing
; them if need be.  i.e. get_uic requires the file to have been Displayed,
; and if it has not this macro will jsb to fip_display, which in turn will
; check to make sure that it has been Searched...on down to fip_parse if it
; needs to.
      .MACRO $PREPARE_FILE, must=<none>, err, ?label1
         $verify_must_values must
         .if idn <must>, <close>
            bitb #fip$m_open_r!fip$m_open_w, fip$f_flags(r2)
            beql label1
            jsb  fip_close
         .iff
            bbs #fip$v_'must , fip$f_flags(r2), label1
            jsb fip_'must
         .endc
         .iif not_blank <err>, $onerr err
label1:
      .ENDM
;============================
; to return rs or es (if file not successfully Searched) and its length
; through the appropriate parameters.
      .MACRO $RETURN_FILE, ?label1, ?label2, ?label3
         bbs  #fip$a_ofile, r3, label1
         bbs  #fip$a_olen, r3, label1
         brb  label3
label1:
         bbc     #fip$v_search, fip$f_flags(r2), label2
         jsb     fip_get_rs
         brb     label3
label2:
         bbc     #fip$v_parse, fip$f_flags(r2), label3
         jsb     fip_get_es
label3:
      .ENDM
;============================
; this puts the arg-mask into the low byte of r3, clearing the rest for use
; as "call" flags
      .MACRO $GET_ARGM, reg=<r3>
         jsb argm_r2
         movzwl r0, reg
         movl   #1, r0
      .ENDM
;============================
; makes sure that a required parameter is provided.  else returns error code.
      .MACRO $CHECK_ARG, arg, data=<r3>, err, ?label1
         .iif blank <arg>,  .error 0; missing argument to $CHEC_ARG
         bbs #arg, data, label1
         movl #cli$_reqprmabs, r0
         .iif not_blank <err>, jmp err
label1:
      .ENDM
;============================