9 Auxiliary routines

The following auxiliary routines are currently available.

• CALL oasis_abort (compid, routine_name, abort_message, rcode)
• CALL prism_abort_proto(compid, routine_name, abort_message)
  • compid [INTEGER; IN]: component ID (from oasis_init_comp)
  • routine_name[CHARACTER*; IN]: name of calling routine
  • abort_message[CHARACTER*; IN]: message to be written out.
  • rcode [INTEGER, OPTIONAL; IN]: Optional argument. When OASIS aborts, it returns rcode if it is present, else it returns 1

  If a process needs to abort voluntarily, it should do so by calling oasis_abort. This will ensure a proper termination of all processes in the coupled model communicator. This routine writes the name of the calling component, the name of the calling routine, and the message to the process debug file (see $NLOGPRT in section 3.2). This routine cannot be called before oasis_init_comp.

  
  

• CALL oasis_get_debug(debug_value)
• CALL prism_get_debug(debug_value)
  • debug_value [INTEGER; OUT]: debug value

  This routine may be called at any time to retrieve the current OASIS3-MCT internal debug level (see $NLOGPRT in section 3.2). This is useful if the user wants to return the original debug value after changing it.

  
  

• CALL oasis_set_debug(debug_value)
• CALL prism_set_debug(debug_value)
  • debug_value [INTEGER; IN]: debug value

  This routine may be called at any time to change the debug level in OASIS3-MCT. This method allows users to vary the debug level at different points in the component integration.

  
  

• CALL oasis_get_intercomm(new_comm, cdnam, kinfo)
• CALL prism_get_intercomm(new_comm, cdnam, kinfo)
  • new_comm [INTEGER; OUT]: mpi intercomm communicator
  • cdnam [CHARACTER*; IN]: other component name (i.e. 2nd argument of the call to oasis_init_comp in that component)
  • kinfo [INTEGER; OUT; OPTIONAL]: returned error code

  This routine sets up an MPI intercomm communicator between the root processors of two components, the local component and the component associated with cdnam. This call is collective across the tasks of the two components but other components are not involved.

  
  

• CALL oasis_get_intracomm(new_comm, cdnam, kinfo)
• CALL prism_get_intracomm(new_comm, cdnam, kinfo)
  • new_comm [INTEGER; OUT]: mpi intracomm communicator
  • cdnam [CHARACTER*; IN]: other component name (i.e. 2nd argument of the call to oasis_init_comp in that component)
  • kinfo [INTEGER; OUT; OPTIONAL]: returned error code

  This routine sets up an MPI intracomm communicator between the root processors of two components, the local component and the component associated with cdnam . This call is collective across the tasks of the two components but other components are not involved.

• CALL oasis_put_inquire(var_id, date, kinfo)
• CALL prism_put_inquire_proto(var_id, date, kinfo)
  • var_id [INTEGER; IN]: field ID (from corresponding oasis_def_var)
  • date [INTEGER; IN]: as in oasis_put, number of seconds (or any other time units as long as the same are used in all components and in the namcouple) in the run at the time of the call
  • kinfo [INTEGER; OUT]: returned info code
    • OASIS_Sent(=4) if the field would be sent to another component
    • OASIS_LocTrans (=5) if the field would be only used in a time transformation (not sent, not output)
    • OASIS_ToRest (=6) if the field would be written to a restart file only
    • OASIS_Output (=7) if the field would be written to an output file only
    • OASIS_SentOut (=8) if the field would be both written to an output file and sent to another component (directly or via OASIS3 main process)
    • OASIS_ToRestOut (=9) if the field would be written both to a restart file and to an output file.
    • OASIS_Ok (=0) otherwise and no error occurred.

  This routine may be called at any time to inquire what would happen to the corresponding field (i.e. with same var_id and at same date) below the corresponding oasis_put. This maybe useful if, for example, the calculation of a coupling field is costly and if one wants to compute it only when it is really sent out.

• CALL oasis_get_ncpl(var_id, ncpl, kinfo)
• CALL prism_get_ncpl_proto(var_id, ncpl, kinfo)
  • var_id [INTEGER; IN]: field ID (from corresponding oasis_def_var)
  • ncpl [INTEGER; OUT]: number of coupling exchanges in which the field is involved (i.e. when a field is sent to multiple targets)
  • kinfo [INTEGER; OUT]: returned info code

  This routine returns the number of coupling exchanges in which the field var_id is involved. This number is needed to get the coupling frequencies with the routine oasis_get_freqs, see below.

• CALL oasis_get_freqs(var_id, mop, ncpl, cpl_freqs, kinfo)
• CALL prism_get_freqs_proto(var_id, mop, ncpl, cpl_freqs, kinfo)
  • var_id [INTEGER; IN]: field ID (from corresponding oasis_def_var)
  • mop [INTEGER; IN]: OASIS_Out or OASIS_In type
  • ncpl [INTEGER; IN]: number of couplings in which the field is involved (i.e. when a field is sent to multiple targets)
  • cpl_freqs [INTEGER; DIMENSION(ncpl); OUT]: coupling period(s) (in number of seconds) of field var_id. There is one coupling period for each coupling exchange in which the field is involved
  • kinfo [INTEGER; OUT]: returned info code

  This routine can be used to retrieve the coupling period(s) of field with corresponding var_id, as defined in the namcouple