*! version 1.0.0 04apr2021

try -- Call a Stata command repeatedly until it succeeds

Syntax

Standard syntax

try : stata_cmd

Full syntax

try [#]
[, tmax(#) verbose nodots] : stata_cmd

where # specifies the upper limit on the number of times that stata_cmd
will be called. The default is 30.

Description

try calls stata_cmd up to a certain number of times, with a random
sleep of between 500-1000 milliseconds before each subsequent attempt.
Calls are stopped after the first successful execution of the command.

A common use for try is to avoid the problem of export excel
timing out on a network.

Options

tmax(#) specifies the upper limit in seconds on the total time that
Stata will sleep; default tmax(900).

verbose reports the number of attempts and the total sleep time.

nodots specifies whether to display iteration dots.
By default, one dot is displayed for each attempt.

Remarks

If unsuccessful, try will stop calling stata_cmd when the
accumulated sleep time will exceed the sleep time in tmax(), or
when the number of requested attempts is reached, whichever comes first.

With the default number of attempts being 30, the expected total sleep
time is 22.5 seconds. Thus the following will stop after 30 attempts

. try, tmax(60): ...

If you want try to run up to 60 seconds, irrespective of the number of
attempts, code

. try ., tmax(60): ...

Examples

Typical use

. try: export excel ...

As above, but call export excel up to 20 times instead
of the default 30 times

. try 20: export excel ...

Call export excel up to 100 times but spend no longer than 60 seconds

. try 100, tmax(60): export excel ...

Call export excel for up to 60 seconds, irrespective of the number of attempts

. try ., tmax(60): export excel ...

Report the number of attempts and the total sleep time

. try, verbose: export excel ...

Authors

Rafal Raciborski

rraciborski@gmail.com