What does "include step output in history"-setting control in SQL Server Agent for TSQL steps?

Question

When you create a TSQL job step, there's an advanced setting called: "Include step output in history", but I don't understand what this setting controls:

A sample job script:

DECLARE @jobId BINARY(16)
EXEC  msdb.dbo.sp_add_job @job_name=N'SampleJob', 
        @enabled=1, 
        @notify_level_eventlog=0, 
        @notify_level_email=2, 
        @notify_level_netsend=2, 
        @notify_level_page=2, 
        @delete_level=0, 
        @category_name=N'[Uncategorized (Local)]', 
        @owner_login_name=N'', @job_id = @jobId OUTPUT

EXEC msdb.dbo.sp_add_jobstep @job_name=N'SampleJob', @step_name=N'Include step in history', 
        @step_id=1, 
        @cmdexec_success_code=0, 
        @on_success_action=1, 
        @on_fail_action=2, 
        @retry_attempts=0, 
        @retry_interval=0, 
        @os_run_priority=0, @subsystem=N'TSQL', 
        @command=N'print ''Include step in history''', 
        @database_name=N'master', 
        @flags=4

EXEC msdb.dbo.sp_add_jobserver @job_name=N'SampleJob', @server_name = null

Regardless if it's checked or not, I can't get the step output to show up in job history:

Note that I have a CMD command which does output into history.

So, it seems this setting doesn't control anything for TSQL job steps, or does this output somewhere else?

Note that I don't have any problem with "Log to table" / "Append output" settings, they control sysjobstepslogs output.

Note #2, all step outputs are being added to sysjobhistory, regardless if this flag is set or not, so that doesn't seem to be it either.

Answer 1

After some collaboration and experimentation, we've determined that the checkbox will show resultset output in sysjobhistory - as long as no other output-affecting statements, like PRINT or RAISERROR, are executed in the same step.

If you check the box "Include step output in history":

1. The following step:

    SELECT foo = 'step 1';
   

   Will lead to the following row in sysjobhistory (cr/lf added by me):

    Executed as user: <whoever>. 
   
    foo
    ------
    step 1
   
    (1 rows(s) affected).  
   
    The step succeeded.
   

2. The following step:

    SELECT foo = 'step 2';
    PRINT 'this is the second step';
   

   Results in the following row in sysjobhistory, without the resultset output:

    Executed as user: <whoever>. 
   
    this is the second step [SQLSTATE 01000] (Message 0).  
   
    The step succeeded.
   

If you want the step output to reliably end up somewhere, regardless of the rest of the job step (or any future changes), also choose the "Log to table" option - in which case the output will be captured in sysjobstepslogs even when it is suppressed from sysjobhistory. Those same two steps would produce the following in the log column. Step 1 (without print):

Job 'testing' : Step 1, 'step 1 - without print' : 
Began Executing <whenever>

foo   
------
step 1

(1 rows(s) affected)

Step 2 (with print):

Job 'testing' : Step 2, 'step 2 - with print' : 
Began Executing <whenever>

foo   
------
step 2

(1 rows(s) affected)

this is the second step [SQLSTATE 01000]

Just be wary of how much output you might have, because this could blow up msdb if you aren't careful.