
.. _queue_cli:

queue
*****







.. rubric:: Output of :code:`--help=queue`



The following help text is generated by :code:`ecflow_client --help=queue`

::

   
   queue
   -----
   
   QueueCmd. For use in the '.ecf' script file *only*
   Hence the context is supplied via environment variables
     arg1(string) = queue-name:
     arg2(string) = action: [active | aborted | complete | no_of_aborted | reset ]
        active: returns the first queued/aborted step, the return string is the queue value from the definition
        no_of_aborted: returns number of aborted steps as a string, i.e 10
        reset: sets the index to the first queued/aborted step. Allows steps to be reprocessed for errors
     arg3(string) = step: value returned from step=$(ecflow_client --queue=queue_name active)
                   This is only valid for complete and aborted steps
     arg4(string) = path: (optional). The path where the queue is defined.
                    By default we search for the queue up the node tree.
   
   If this child command is a zombie, then the default action will be to *block*,
   The default can be overridden by using zombie attributes.If the path to the queue is not defined, then this command will
   search for the queue up the node hierarchy. If no queue found, command fails
   
   Usage:
   step=""
   QNAME="my_queue_name"
   while [1 == 1 ] ; do
      # this return the first queued/aborted step, then increments to next step, return <NULL> when all steps processed
      step=$(ecflow_client --queue=$QNAME active) # of the form string  i.e "003". this step is now active
      if [[ $step == "<NULL>" ]] ; then
           break;
      fi
      ...
      ecflow_client --queue=$QNAME complete $step   # tell ecflow this step completed
   done
   
   trap() { ecflow_client --queue=$QNAME aborted $step # tell ecflow this step failed }
   
   
   The client considers, for both user and child commands, the following environment variables:
   
     ECF_HOST <string> [mandatory*]
       The main server hostname; default value is 'localhost'
     ECF_PORT <int> [mandatory*]
       The main server port; default value is '3141'
     ECF_SSL <any> [optional*]
       Enable secure communication between client and server.
     ECF_HOSTFILE <string> [optional]
       File that lists alternate hosts to try, if connection to main host fails
     ECF_HOSTFILE_POLICY <string> [optional]
       The policy ('task' or 'all') to define which commands consider using alternate hosts.
   
   The options marked with (*) must be specified in order for the client to communicate
   with the server, either by setting the environment variables or by specifying the
   command line options.
   
   The following environment variables are used specifically by child commands:
   
     ECF_NAME <string> [mandatory]
       Full path name to the task
     ECF_PASS <string> [mandatory]
       The job password (defined by the server, and used to authenticate client requests)
     ECF_TRYNO <int> [mandatory]
       The run number of the job (defined by the server, and used in job/output file name generation.
     ECF_RID <string> [mandatory]
       The process identifier. Supports identifying zombies and automated killing of running jobs
     ECF_TIMEOUT <int> [optional]
       Maximum time in *seconds* for client to deliver message to main server; default is 24 hours
     ECF_DENIED <any> [optional]
       Allows task to exit with an error, upon connection failure, thus avoids ECF_TIMEOUTs wait.
     NO_ECF <any> [optional]
       If set, ecflow_client exits immediately with success; useful to test the scripts without a server
   
   The scripts are expected to export the mandatory variables, typically in shared include files
   

