Chapter 12. Terminal

12. Terminal

The ReportServer Terminal is a mighty tool for administrators. You open it with the keyboard shortcut CTRL+ALT+T (Please consider that you need the respective rights; refer to Chapter 3. User and Permission Management).

The ReportServer Terminal follows the shell of a Unix system. It includes a command prompt as well as a history of commands and the respective outputs. Beside general commands, the Terminal provides access to almost all ReportServer objects via the Virtual file system. In addition, the Terminal can be used to enter and execute scripts.

12.1. Using the Terminal

Enter commands at the command prompt and confirm with ENTER. The following command:

reportserver$ hello

will return the reply

> hello user

There are two different types of commands. Simple commands will provide their output directly in the Terminal. This applies for the majority of commands. Beside the simple ones there are also commands requiring further user interaction. After calling up this type of command, the command prompt will change and display a single opening angle bracket. The eliza program represents an example for this command type (originally by Joseph Weizenbaum, and here in an adaptation by Jesper Juul). You close complex commands with CTRL+C, or according to eliza also by entering the leave-taking expression: bye

reportserver$ eliza
**************************
ELIZA
CREATIVE COMPUTING
MORRISTOWN, NEW JERSEY
ADAPTED FOR IBM PC BY
PATRICIA DANIELSON AND PAUL HASHFIELD
Java version February 24th, 1999
By Jesper Juul - jj@pobox.com.
**************************
> Hi, my name is Bob.
HI! I"M ELIZA. WHAT"S YOUR PROBLEM?
I DON"T CARE ABOUT NAMES --PLEASE GO ON.
> I do not know. Isn"t that why I am here?
HOW LONG HAVE YOU BEEN HERE?
> About one minute or so.
WHAT DOES THAT SUGGEST TO YOU?
> I guess you cannot help me after all.
OH, I CANNOT HELP YOU AFTER ALL.
> bye
Good Bye
reportserver$

The -h flag (or -? flag) offers help to a command listing the individual options. When pressing the TAB key, ReportServer attempts to complete the command presently entered. If it fails to do so because there are several options, these will be shown to you by pressing the TAB key again. With the arrow keys UP/DOWN you browse through the history of your commands. To clear the Terminal window, use the clear command.

You can leave the Terminal by entering the exit command.

You will find a command overview including a short description of all available commands in Chapter 14.

Tip: To copy data from the Terminal window, press the CTRL key when selecting the data. Otherwise, the cursor in the command prompt will be activated when clicking on the window.
12.2. The Virtual File System

ReportServer integrates various objects (reports, data sources, files, etc.) as virtual file systems in the Terminal. Each object tree (e. g. the report section) has here an own root node. When you open the Terminal you first arrive at the top level. Here you find the root nodes of the various virtual file systems. By entering the command ls you can display them.

reportserver$ ls
datasources					Data source management
reportmanager				Report management
dadgetlib						Dadget library
fileserver 					File system
tsreport 						TeamSpaces 
usermanager 				User management

Here ls shows the objects in the current directory. By entering the command pwd the current directory will display.

reportserver$ pwd
/

Use the command cd directory to change the directory. Multiple folders will be separated by / (slash). So, by entering

cd "reportmanager/Dynamic Lists/"

you can switch to the folder Dynamic lists in the report management tree. Please observe to set quotation marks when there are objects that include spaces in their name. When you enter mkdir, you can create a new sub-folder.

reportserver$ mkdir newFolder reportserver$ ls -l
12 T_AGG_ORDER - Basis TableReport			TableReport
17 T_AGG_PAYMENT - Basis								TableReport
22 T_AGG_CUSTOMER - Basis								TableReport
26 T_AGG_PRODUCT - Basis								TableReport
33 T_AGG_EMPLOYEE - Basis								TableReport
39 T_AGG_ORDER - Parametrized 					TableReport
49 newFolder 														ReportFolder

This is the output of ls -l which returns name and object as well as ID and type. Now, to move all reports to the new folder, use

reportserver$ mv T_AGG_* newFolder/ 
reportserver$ ls -l newFolder
17 T_AGG_PAYMENT - Basis 						TableReport 
33 T_AGG_EMPLOYEE - Basis 					TableReport 
12 T_AGG_ORDER - Basis 							TableReport
22 T_AGG_CUSTOMER - Basis 					TableReport 
39 T_AGG_ORDER - Parametrized 			TableReport 
26 T_AGG_PRODUCT - Basis 						TableReport

Be aware that the mv command at present expects the second parameter always to be a directory in contrast to the Unix equivalent. This is why it cannot be used to rename objects.

Now we switch to the FileServer and create a temporary directory:

reportserver$ cd /fileserver/
reportserver$ mkdir tmp
reportserver$ cd tmp
reportserver$ pwd
/fileserver/tmp

Unlike typical file systems, ReportServer allows two objects having the same name in one folder. For example, two reports with identical names will be in the same report section. We can simulate this by creating two folders with the same name:

reportserver$ mkdir test
reportserver$ mkdir test
reportserver$ ls -l
124 		test		FileServerFolder
125 		test 		FileServerFolder

Now, what will happen if we change to the test folder by entering cd test?

reportserver$ cd test
reportserver$ pwd
/fileserver/tmp/test

We have switched to the test folder. But to which one did we switch? Internally, ReportServer saves paths not via their names, but via the ID of objects which are unique in the individual virtual file systems. By entering pwd -i they will display.

reportserver$ pwd -i
/fileserver/id:123/id:124

As you see, we changed to the first test folder with the ID 124. To get to the second one with the ID 125, use the internal path:

reportserver$ cd ../id:125
reportserver$ pwd
/fileserver/tmp/test
reportserver$ pwd -i
/fileserver/id:123/id:125

In FileServer (i.e. in the virtual file system which represents ReportServer FileServer) we can use the commands createTextFile and editTextFile to create or edit text files.

reportserver$ createTextFile text.txt
file created

By entering cp now we can copy this text to other folders.

reportserver$ cp text.txt ..
reportserver$ cd ..
reportserver$ ls -l
124			test 				FileServerFolder
125 		test				FileServerFolder
127 		text.txt 		FileServerFile

To delete objects, use the rm command. Here wildcards can be used.

reportserver$ rm tes*
/fileserver/tmp/test has children

Here, ReportServer stated that the folder to delete still holds objects. To include them in the deletion, use rm -r.

reportserver$ rm -r tes* 
reportserver$ ls -l
127 		text.txt 		FileServerFile
12.3. Assigning Aliases

For some recurring commands it might be useful to define shortcuts (aliases). To do this, use the configuration file etc/terminal/alias.cf (You will find it in the ReportServer File system, from the Terminal you will access it by entering /fileserver/etc/terminal/). If the file does not exist, create the respective directories by entering mkdir and the file with createTextFile.

The file is structured as follows

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
	<cmdaliases>
		<entry>
			<alias>ll</alias>
			<command>ls -l</command> 
		</entry>
   	</cmdaliases>
</configuration>

Here, alias ll was assigned to the command ls -l. To reload the aliases, use:

reportserver$ config reload
configuration reloaded
reportserver$ updateAlias
alias table updated

First, the cache which stores all configuration files will be cleared by entering config reload. Then you can re-enter the alias configuration with the command updateAlias. After a Report- Server restart it will be loaded automatically.

12.4. Scripts

A main task of the Terminal is to manage and execute scripts. In ReportServer scripts can be used for various purposes. Firstly, they can be used to create dynamic or complex reports. As they have access to the Java runtime environment and with this to the available metadata, scripts are perfectly suited for reports analyzing the system status. An example for a script report is the documentation report (for further information on script reports refer to Section 6.9.). In addition, scripts can also be used for administrative tasks, or even to expand the functionality of ReportServer. Within the scope of this Administrator manual, we will give you some insight into the world of ReportServer scripts in the following section. You will find a detailed treatment including examples and concepts in our script guide.

Warning: The right to write scripts allows a user to execute arbitrary code. This right should thus only be granted to trusted system administrator's.

12.5. Object Resolver

The following describes how to locate entities. Entities are stored objects such as reports, users or TeamSpaces. You can find entities by searching for classes annotated with @Entity. You can also find a list of all entities in our ReportServer SourceForge project https://sourceforge.net/projects/dw-rs/. Download the latest apidocs file from the src directory for this.

Many terminal commands provide you with an object resolver to find a specific entity or a group of entitities. Currently, there are three object resolvers:

ID Resolver Allows you to locate an entity by its entity ID.
Path Resolver Allows you to find an entity by its Virtual File System path.
HQL Resolver Allows you to find entities by a HQL (Hibernate Query Language) query.

We will illustrate these object resolvers by using the locate command. Any other command supporting object resolvers works analogously to the examples provided below.

The locate command allows you, as its name suggests, to locate entities by using an object resolver query. Refer to the locate command documentation for more information on this.

The ID object resolver uses an entity ID for locating an entity. Since entity IDs are unique, the query resolves to zero or one entity. The syntax is: id:EntityType:entityId where EntityType is the specific entity class, e.g. TableReport. Refer to the entity list mentioned above for the specific entity types. entityId is the specific entity ID. E.g.:

reportserver$ locate id:TableReport:123
Report Root/Dynamic Lists/myReport (Reportmanager)

The path resolver requires a Virtual File System path for locating the specific entity. Note that the path requires quotation marks if it contains spaces. E.g.:

reportserver$ locate "/reportmanager/Dynamic Lists/myReport"
Report Root/Dynamic Lists/myReport (Reportmanager)

You can also insert a relative path to the current location, e.g.:

reportserver$ locate myReport
Report Root/Dynamic Lists/myReport (Reportmanager)

Further, you can use an HQL query (Hibernate Query Language) for locating the needed entity or group of entities. Refer to https://docs.jboss.org/hibernate/orm/5.0/userguide/en-US/html/ch13.html for the HQL documentation. The syntax is: hql:query where the query is a valid select HQL query. Since HQL queries have blank spaces, quotation marks are needed. E.g.:

reportserver$ locate "hql:from TableReport where id=123"
Report Root/Dynamic Lists/myReport (Reportmanager)

You can also search for entity attributes, e.g.:

reportserver$ locate "hql:from TableReport where name like '\%myReport\%'"
Report Root/Dynamic Lists/myReport (Reportmanager)
Report Root/myReport2 (Reportmanager)