Category: Documentation

Duh, it’s on the web, you say. Yes, of course it is, but sometimes you prefer to have a local copy of the documentation. For instance:

• You are behind a firewall. Yes, you might be sitting on a jumpbox or even the server without access to Internet and need the documentation.
• You want instant overview of contents. Ever tried to see what the contents for the help is on the web-based help? Yeah, in the end you rely on Google. Sometimes you just want to have an immediate response when you navigate the contents, from the root to the leaf.

First of all, you have two options in SSMS for the F1-help: Web-based or local (which means the Help Viewer tool). Web-based is default, so we don’t need to dive further into that.

But you will now notice that you don’t have any contents. So, do “Add and Remove Help Content”. I have imploded all but the SQL server books below:

Just “Add” it and then press the “Update” button on the lower right of the window.

How do I get to the help?

You can do F1 from a query window. Type for instance SELECT, mark the word and press F1. Many keywords and such has entries into the help to get you to the right place immediately. Just like the web-based help.

Another option is to create a shortcut for the help. I use the Classic Start Menu tool (how can you else use windows?) and I have a shortcut for the help, named “BOL 2019”.

The tricky part is what to point to. Here is what I have

Start in: “C:\Program Files (x86)\Microsoft Help Viewer\v2.3”
Target: “C:\Program Files (x86)\Microsoft Help Viewer\v2.3\HlpViewer.exe” /catalogName SSMS18 /locale en-US

Tips

You can switch what F1 does in SSMS at any time. So even if you have downloaded the books, but you now want F1 to take you to the web-based help, then just switch to that.

The local help has an entry at the right top to take you to the webpage when you have some page open.

When you have found a page in the local help, be it from F1, the index or a search, you sometimes want to “know where you are”. I.e., see the contents and surrounding topics etc:

This seems to be a never ending story, having a locally installed Books Online for SQL Server, that is. Some of you recall that I have posted about this before. This post is about my experiences for the current state of Books Online. Things has changed since I last blogged this. Among other things, MS has re-worked the documentation, including moving the online bit from MSDN to docs.

Background: I have a new machine, and with that I of course want to have a local Books Online for SQL Server. Following any of my previous post didn’t quite work. Here is what I installed:

• Windows 10, fresh installation
• SQL Server 2016 (Db engine, SSIS, SSRS)
• Patch above to current service pack and CU.
• SQL Server Data Tools – BI
• SSMS 17.2
• Visual Studio 2017

There are of course other stuff on the machine as well, but I doubt that affect the SQL Server BOL experience. Here’s what I did to get local BOL inside SSMS:

1. Help
2. Add and Remove Help Content
3. Under “SQL Server” header, I just added the bits that I found interesting. In my case everything.
4. Update
5. Now it took a long while, since I missed the VS installation a monster-sized doc for Framework. I later removed the VS bits.
6. I was also afraid that I experienced a bug in Help Viewer, where it would hang. It took a long while with status something like removing temp files. But it ended just fine, I didn’t have to do the “kill, update help config file, and stuff”, like I did before.

Bottom line is that it worked just as I expected, or perhaps I should say “hoped for”. 🙂
(Well, almost. Some entries are doubled. I don’t actually bothered (much) about that so I just ignore that. For instance under “SQL Server Technical Documentation” I have two of both “Overview” and “Release Notes”.)

What more? Well, we probably want local BOL to be the “F1”-help:

1. Help
2. Set Help Preference
3. Launch in Help Viewer

Also, your might want to create a shortcut (on desktop, start menu, or wherever), which points to:
C:\Program Files (x86)\Microsoft Help Viewer\v2.2\HlpViewer.exe” /catalogName SSMS17 /locale en-US

For reference, here are two prior posts on the subject. But don’t go there, they will confuse you. I only list them here as a reference, and *in case* you might end up with a hung help viewer etc…
Bol 2016 blog 1
Bol 2016 blog 2

Good news, everybody! Microsoft recently released an update for the local Books Online, with a functioning index for the relational engine.

Earlier versions were missing those index bits, but not for everyone (a theory is that it depends on what server you hit when you downloaded the BOL bits). Basic steps to get them (see my earlier blog, linked to at the end of this, for details):

• SSMS 2016
• Help
• Add and Remove Help Content. This opens Help Viewer 2.2 (HW).
• If you have the old BOL bits, you should see that there is an update:
  • Remove them
  • Update
  • HW might hang at the end, force-finish it.
• Add the relevant BOL bits (under Recommended Documentation), the ones under “SQL Server” is for 2012.
• Update
• HW might hang at the end, force-finish it.

There are other issues with BOL to hopefully be addressed. See my earlier blog post for details.

This one is for those of you who prefer to use a local SQL Server Documentation, a.k.a. Books Online (BOL), instead of using the web-based BOL. A local BOL is essential for me. Navigating the contents, switching between pages and searching is lightyears ahead and quicker in the local BOL.

(Update: Added bits about the missing index.)

(Update 2: there now is a functioning index.)

Erland Sommarskog (http://www.sommarskog.se/) is possibly even more adamant that I am about having a local BOL and he has been very helpful. Also thanks to Carla Sabotta and Jennifer Hubbard for the help and patience.

Getting a functional BOL for SQL Server 2016 is a bit more complicated than for 2014. In this earlier blog post I discussed how to get a proper Table of Contents for the 2014 BOL.

Some basics about the local BOL (from now on I call this BOL):

• It uses HelpViewer.
•    SQL Server 2012 and 2014 used HelpViewer 1.1.
•    SQL server 2016 uses HelpViewer 2.2.
• F1 from within SSMS will always take you to the web based BOL.
• When you install the SQL Server 2016 engine (not SSMS) you get two program entries. Ignore these:
•    “SQL Server Documentation” opens the old HelpViewer 1.1. There is no 2016 BOL for HelpViewer 1.1.
•    “Manage Help Settings” takes us to the old Help Library Manager, which is for HelpViewer 1.1.

There is no stand-alone download for the 2016 books (which you would unpack on your harddrive, as we had to do for BOL 2014). You need to do it from inside the HelpViewer 2.2 program. Here’s how to do it:

From inside SQL Server Management Studio (SSMS):

• “Help”
• “Add and Remove Help Content”. This opens HelpViewer 2.2.
• Make sure that “Online” is selected.
• Add the SQL Server 2016 parts. Don’t do what I did and look for a “SQL Server 2016” header in bold typeface. The 2016 parts is right under your nose, under “Recommended Documentation”.
• “Update”

Unfortunately there is currently a bug in HelpViewer 2.2 and it will freeze. See https://msdn.microsoft.com/library/mt654096.aspx on how to handle this. You only need to do these steps once, but you will probably need to end HelpViewer in the Task Manager whenever you update your content.

Now you should have the 2016 BOL. Selecting “Help”, “View Help” from SSMS will still open the web-based BOL, though (a web-browser inside SSMS). So to open the local BOL 2016 from inside SSMS, you will use:

• “Help”
• “Add and Remove Help Content”. (Yes, the same that you used to add the books.)

(Update) Note that the index isn’t there for the relational database engine, including T-SQL reference. If you for instance in the index type GROUP BY or @@SERVERNAME you will either get no hits, or be taken to the SQL Server 2012 documentation assuming you also installed that). We’ll see if MS will build an index for the relational database topics. My contacts at MS say that they do have an index, where I don’t. What do you see? Please let us know below if you, after installed BOL 2016 according to this blog post has a working index for the relational database engine. For instance if you get a 2016 hit for GROUP BY.(/Update)

(Update 2): I today, 2016-09-05, noticed that MS recently released an update for BOL 2016 and the index is there. Yay! (/Update2)

How about a program icon from which you can start BOL 2016 outside of SSMS? Create shortcut somewhere which point to below:
“C:\Program Files (x86)\Microsoft Help Viewer\v2.2\HlpViewer.exe” /catalogName SSMS16 /locale en-US

What if you don’t have SSMS installed, but still want a local BOL? There’s nothing from the SQL Server team to help you here. You would have to install HelpViewer 2.2 on your own (something I haven’t bothered to investigate).

See https://msdn.microsoft.com/en-US/library/mt736393(SQL.130).aspx and https://msdn.microsoft.com/en-us/library/mt703151(v=sql.1).aspx
(the later is a bit more generic).

As you probably know, the SQL Server Documentation (aka Books Online or BOL) as of SQL Server 2012 takes us to a web-site. Searching and navigating a web-site when you want rapid and precise help is a horrible experience.

• Fortunately, there’s still a local BOL.
• Unfortunately, the local BOL for SQL Server 2014 has been broken for a long time.
• Fortunately, there is a way to fix it.

The trick is to not do it how you are supposed to do it. At least not all steps. Here’s how to get a functional local BOL:

1. Download the help files from https://www.microsoft.com/en-us/download/confirmation.aspx?id=42557
2. Unpack the files somewhere
3. Open the Manage Help Settings application
4. “Choose online or local help”
5.  Select “I want to use local help”
6. OK
7. Do not select “Install content from Online”. This is where you need to divert from how you (generally) are supposed to do it.
8. “Install content from disk”
9. Point to wherever you unpacked the files in step 2 above
10. “Add” all books
11. “Update”

So it is only a matter of downloading the files ourselves instead of letting the Help Library Manager (“Manage Help Settings”) tool do it.

If you wonder in what way the BOL is broken, then it is the Table of Content (TOC) which lacks a lot of subjects (for instance the T-SQL reference lacks bunch of things).

I just learned from Gail E. at MS that the system error messages are all documented in the SQL Server 2008 Books Online.

For instance, search for 823. See the hits? Now, for instance, select the “Errors 1 – 999” page. Press the “Sync with Table of Contents” button. Look to the left, in the “Contents” section. You now see that the errors messages are divided into sections (1-999, 1000-1999, …). You also see where in BOL to find these sections:

SQL Server 2008 Books Online
Database Engine
Technical Reference
Errors and Events Reference
Database Engine Events and Errors
System Error Messages

Also note that some messages has a hyperlink which takes us to a section where we can read more about this particular error message (823 is such an example).