create_blocking_file.m

function blk_file_name = create_blocking_file( varargin )
% CREATE_BLOCKING_FILE - create a temporary file to prevent Matlab from
% continuing execution until some programmatically-specified condition is
% met.
%
% Matlab's various commands to pause execution (waitfor, pause, etc.) will not
% wait for the completion of a windows system call (as of Matlab version
% R2011b).  This is a somewhat inelegant brute-force workaround for this
% problem.  A temporary "blocking" file is created in the directory specified by
% tempname().  The file contains the text "placeholder file to pause Matlab
% execution" and the time the file was created, followed by an optional user
% message (e.g. "this file was create to pause Matlab for XYZ").  The full path
% of the file is returned.  If the last command of the Windows system call
% deletes the blocking file, then placing the following code immediately after
% the system call causes Matlab to wait for the system call to complete before
% continuing:
%
% pause on;
% while( exist( blk_fname ) == 2 )
%     pause( 5 );
% end
% pause off
%
% The blocking file is named PREFIX_blocking_yyyymmdd_HHMMSS.txt, with PREFIX
% a long random string generated by tempname() and yyyymmdd_HHMMSS the output
% of now() converted to a character string.
% 
% USAGE
%    blk_file_name = create_blocking_file();
%    blk_file_name = create_blocking_file( 'optional message for file' );
%
% INPUTS
%    variable: if provided, a character string will be placed in the blocking
%        file.  Additional arguments are ignored.
%
% OUTPUTS
%    blk_file_name: the full path to the blocking file
%
% SEE ALSO
%    tempname, now
%
% author: Timothy W. Hilton, UNM, May 2012





p = inputParser();
p.addOptional( 'user_message', '', @ischar );
p.parse( varargin{ : } );

t_string = datestr( now(), 'blocking_yyyymmdd_HHMMSS' );

blk_file_name = sprintf( '%s%s.txt', tempname(), t_string );
fid = fopen( blk_file_name, 'w' );


fprintf( fid, 'placeholder file to pause Matlab execution\r\n' );
fprintf( fid, 'created %s\r\n', datestr( now() ) );
if not( isempty( p.Results.user_message ) )
    fprintf( fid, '%s\r\n', p.Results.user_message );
end

fclose( fid );