This is the documentation for SuperSTAR 9.8

SuperSTAR 9.9 is now available.
View this page in the SuperSTAR 9.9 documentation or visit the SuperSTAR 9.9 documentation home.

Skip to end of metadata
Go to start of metadata
Use this command to configure the catalogue; the collection of datasets and folders available to SuperSERVER.
ItemDescription
FolderSimilar to a folder in a filesystem, you can use folders to organise the items in the catalogue and group together related items. The folders will be displayed to end users in the client (SuperCROSS, SuperWEB2, etc)
Dataset/DatabaseAn sxv4 file containing the SuperSTAR dataset for cross tabulation.

Use the cat command to:

View Current Catalogue Settings

UsageDescription
cat
Display all the items in the catalogue, including datasets, folders, tables and recode groups, along with their settings.
cat <id>

Display the settings for the specified dataset, folder, table or recode group.

Note: Items in the catalogue have a display name (the name that is displayed to end users in the client) and an ID (a unique identifier). When managing the item in SuperADMIN, you must always use the ID, not the display name.

If a display name or ID includes non alphanumeric characters (e.g. a space) then you must enclose it in quote marks. You must also enclose a display name or ID in quotes if it starts with a numeric character.

cat <dataset_id> fields
List all the fields for the specified dataset.
cat <dataset_id> <field_name>
List all the ID and value set IDs for the specified field.
cat <dataset_id> <field_name> <value_set> values
List all the values for this value set, and their IDs.
cat [ <folder_id> ] databases
List all the datasets in the specified folder (or at the root level if you omit the folder ID).
cat [ <folder_id> ] folders
List all the folders in the specified folder (or at the root level if you omit the folder ID).
cat [ <folder_id> ] tables
List all the tables in the specified folder (or at the root level if you omit the folder ID).
cat [ <folder_id> ] recodegroups
List the recode groups in the specified folder (or at the root level if you omit the folder ID).

Add Datasets and Folders

UsageDescription
cat [ <folder_id> ] adddb <dataset_id> 
[ <display_name> ] <path_location> <server_id>

Add a new dataset to the catalogue.

<folder_id>

(Optional): the folder to install the dataset in. If you omit this the dataset will be installed at the top level of the catalogue.

The Users folder is a special folder that is created by default when SuperSERVER is installed. You are recommended not to add datasets to this folder, because by default all users have access to the Users folder, and therefore all users would automatically have access to any datasets added to this folder.

<dataset_id>

A unique identifier for the dataset. This is the identifier that you will use to manage and configure the dataset in SuperADMIN.

Dataset IDs cannot be longer than 31 characters, and must contain only ASCII characters (this restriction only applies to the ID, which is used internally by SuperSERVER; you can use any Unicode characters you like in the dataset display name, which is the name displayed to users in the clients).

<display_name>

(Optional): a display name for the dataset. This is what users will see in the client (SuperCROSS, SuperWEB2, etc).

For example, if the ID is bank, the display name might be "Retail Banking".

  • Use double quotes if the display name contains a space.
  • If you omit the display name it will automatically be set to the same value as the ID.
<path_location>
The location of the sxv4 file that contains the dataset. This can either be an absolute path or a location relative to the SuperSERVER program data directory (in a default installation, this is C:\ProgramData\STR\SuperSERVER SA). The location must be accessible from the machine that SuperSERVER is installed on.
<server_id>
The network name of the machine running SuperSERVER.
cat [ <folder_id> ] addfolder <new_folder_id> 
[ <display_name> ]

Create a new folder.

<folder_id>
(Optional): the folder to create the folder in. If you omit this the folder will be created at the top level of the catalogue.
<new_folder_id>

A unique identifier for the new folder. This is the identifier that you will use to manage and configure the folder in SuperADMIN.

<display_name>

(Optional): a display name for the folder. This is what users will see in the client (SuperCROSS, SuperWEB2, etc).

  • Use double quotes if the display name contains a space.
  • If you omit the display name it will automatically be set to the same value as the folder ID.
cat [ <folder_id> ] addrecodegroup <recode_group_id> 
[ <display_name> ] <path_location>

This command has been deprecated and is no longer used. It was previously used to add groups of saved recodes or User Defined Fields (UDFs) to the catalogue for use in older SuperSTAR clients. SuperCROSS and SuperWEB2 have their own mechanisms for accessing these items and cannot access recode groups or user defined fields that have been added to the catalogue via this command.

Add a group of recodes to the catalogue.

<folder_id>
(Optional): the folder to add the recodes to. If you omit this the recodes will be added at the top level of the catalogue.
<recode_group_id>

A unique identifier for the recode group. This is the identifier that you will use to manage and configure the group in SuperADMIN.

<display_name>

(Optional): a display name for the recode group. This is what users will see in the client.

  • Use double quotes if the display name contains a space.
  • If you omit the display name it will automatically be set to the same value as the recode group ID.
<path_location>
The location of the file that contains the recode information. This can either be an absolute path or a location relative to the SuperSERVER installation directory, but it must be accessible from the machine that SuperSERVER is installed on.

Modify Datasets and Folders

UsageDescription
cat <id> {up|down}

Change the order items are listed in the catalogue (the order of items in the catalogue is also the order they will be displayed to users in the clients).

Use this command to move an item up or down the list.

cat <id> move <folder_id>

Move the specified item into the specified folder.

To move an item to the top level of the catalogue, use the folder ID root. For example:

cat myDataset move root
cat <dataset_id> location <new_path_location>

Replace the dataset with a new version of the SXV4, located at the specified file location.

This command is designed to allow you to update to a newer version of an existing dataset. For example, if you have customer data or survey results that are updated on a regular basis.

The new dataset must be compatible with the existing one. See Update a Dataset for full details.

cat [ <id> ] displayname <new_display_name>

Change the display name of the specified dataset, folder, table, or recode group.

If you omit the <id> then this command will change the display name of the SuperSTAR server (this display name is visible to end users in SuperCROSS, in the Select Database or Table dialog). The default server display name is SuperSTAR Database Server. You can change this to something more meaningful to your deployment. For example:

cat displayname "Initech Datasets"
cat <id> id <new_id>

Change the ID of the specified dataset, folder, table or recode group.

You are recommended not to change IDs, but if you do you will need to restart SuperSERVER and re-apply all the user permissions for the catalogue item.

cat {<dataset_id>|<folder_id>} multilingual {true|false}
Set the dataset or folder to be multilingual. This setting is used in conjunction with multilingual metadata to display dataset/table names, and field names in multiple languages. See Metadata and Multilingual Tables - SuperCROSS for more details on setting up multilingual metadata.
cat remove <id>

Remove the specified dataset, folder, table, or recode group from the catalogue.

Removing a folder will remove all the datasets within that folder.

Set and Check User Access Permissions

ParameterDescription
cat <id> [ <item> ] access {<user>|<group>}
Check what permissions the specified user or group has over the specified dataset, folder, table, or recode group.
cat <id> [ <item> ] access {<user>|<group>} reset
Reset the permissions for this user or group over the specified dataset, folder, table, or recode group to the defaults.
cat <id> permissions
Check which users or groups have permissions set for the specified catalogue item.
cat userpermissions
Check the logged in user's permissions.
cat {<dataset_id>|<folder_id>} [ <item> ] 
access {<user>|<group>|<collection>}
{read|write|readpermissions|writepermissions}
{true|false}

Allow or deny access to the dataset or table.

<dataset_id>

The ID of the dataset or folder you are applying the permission to.

<item>

(Optional): the ID of an item within the dataset to apply security to. If you omit this, the permission is applied to the whole dataset.

The item can be a field, summation option, value, or value set (see these instructions for more information about configuring Field Level Security).

{<user>|
<group>|
<collection>}

The user or group this setting applies to.

Use <collection> to set access permissions for multiple users in one go. Enclose the list of users in square brackets and separate each user with a comma. For example:

cat bank access [user1,user2,user3] read true 
{read|
write|
readpermissions|
writepermissions}

The permission to apply.

  • read - the user can read/view the catalogue item. This allows the user to access the dataset in the client applications. You must give users read access to at least one dataset.
  • write - the user can write/edit/change the catalogue item.
  • readpermissions - the user can query user permissions over the catalogue item. The user will be able to query their own permissions, and those of other users.
  • writepermissions - the user can change user permissions over the catalogue item. The user will be able to change their own permissions, and those of other users.
{true|
false}
  • Set to true to allow this particular permission for the specified user or group.
  • Set to false to deny this particular permission for the specified user or group.

true and false must be lower case.

Manage User Saved Tables

These commands allow you to add saved tables to the catalogue. Any tables you add in this way will only be available to users of SuperWEB2. They do not appear in SuperCROSS.

 If you are running the SuperADMIN console on a different machine to the one running SuperWEB2, then make sure you use the connection command to check and configure the connection to SuperWEB2.

UsageDescription
cat [ <folder_id> ] addtable <table_id> [ <display_name> ] <path_location>

Add a table to the catalogue.

<folder_id>
(Optional): the folder to add the table to. If you omit this the table will be added at the top level of the catalogue.
<table_id>
A unique identifier for the new table. This is the ID that you will use to manage the table in SuperADMIN.
<display_name>

(Optional): a display name for the table. This is what users will see in SuperWEB2.

If you choose not to set the display name then it will be set to the same value as the table ID.

<path_location>
The location on your local disk of the TXD file that contains the table. Once you add the table it will be uploaded to the server and you can move or edit the file on disk.
cat [ <folder_id> ] tables
List all the tables in the specified folder (or at the root level if you omit the folder ID).
cat <table_id> remove
Remove a table from the catalogue.
cat <table_id> move <folder_id>
Move a table to the specified folder.
cat <table_id> displayname
View the current display name of the specified table.
cat <table_id> displayname <new_display_name>
Change the display name of the specified table.

View and Export Tables and Recode Groups

UsageDescription
cat {<table_id>|<recode_group_id>} content

Display the details of the table or recode group. For example:

> cat savedtable1 content
HEADER
        ESCAPE_CHAR & ITEM_BY_CODE
        DBID "bank"
        HEADING "&&o&n&&d&nTable 1&n&&v&n&&s"
        FOOTER "&&r&n&&f&n&&c&n&&p&n&&a"
        ALIGN HEADING CENTRE
.....
cat {<table_id>|<recode_group_id>} export <path_location>
Export the table or recode group to a file. The path location must be a full path to the location to save the file on disk.

Statistical Functions

UsageDescription
cat aggregatestatfunction family name <name> 

Set the aggregated statistical function used by SuperSERVER. This algorithm is used for calculating medians, percentiles and paretos in derivations.

The default is Parzen#1; you can change it to Parzen#2 if necessary, using the following command:

cat aggregatestatfunction family name Parzen#2
If you change this setting, you must restart SuperSERVER to apply the change.
cat [ <dataset_id> ] addstatfunction {mean|median} 

Add a statistical function (mean or median) to the Summation Options in SuperWEB2.

If you specify an ID then the change will apply to that dataset only; if you omit the ID then it will apply to all datasets by default (unless overridden for a specific dataset).

This setting applies to SuperWEB2 only.

cat [ <dataset_id> ] removestatfunction {mean|median} 

Remove a statistical function from the Summation Options in SuperWEB2.

If you specify an ID then the change will apply to that dataset only; if you omit the ID then the function will be removed from all datasets by default (unless overridden for a specific dataset).

This setting applies to SuperWEB2 only.

cat <dataset_id> querystatfunctions

List which statistical functions are currently enabled for the specified dataset.

This setting applies to SuperWEB2 only.

cat <dataset_id> availablestatfunctions

List any statistical functions that are specifically set to be available at the dataset level (i.e., an override has been set at this dataset level).

This will only list available functions that override the default. If you want a full list of available functions for this dataset, use the querystatfunctions command instead.

This setting applies to SuperWEB2 only.

cat <dataset_id> disabledstatfunctions

List any statistical functions that are specifically set to be disabled at the dataset level (i.e., an override has been set at this dataset level).

This will only list disabled functions that override the default. If you want a full list of available functions for this dataset, use the querystatfunctions command instead.

This setting applies to SuperWEB2 only.

cat unitrecord nullhandling {NullAsSkipped|NullAsZero}

Configure how SuperSERVER will handle null values when computing statistical functions on measure fields.

The treatment of null values can affect the result. For example, suppose you have the following set of values: 4, 2, NULL

If you calculate the mean from these values, then the result will either be:

  • 2, if you treat the NULL value as zero: (4+2+0)/3 = 2
  • 3, if you skip the NULL value: (4+2)/2 = 2

The default setting is NullAsSkipped.

If you change this setting, you must restart SuperSERVER to apply the change.

cat unitrecord
Display the current null handling setting.
cat Quantile

Display the current quantile settings.

cat Quantile algorithm {Step|AverageStep|WeightedAverage}

Set the algorithm used for quantile calculations. This algorithm applies to all quantile calculations, including percentiles and the median.

NameDescriptionFormula
StepEmpirical distribution.
AverageStepEmpirical distribution with averaging and interpolation.
WeightedAverageEmpirical distribution with interpolation.

If you change this setting, you must restart SuperSERVER to apply the change.

Take care before changing the quantile algorithm. Changing the quantile algorithm will invalidate any existing saved tables or recodes that contain quantiles based on the previously configured global quantile algorithm.

cat Quantile Buckets [<array_of_integers>]

Set which quantile ranges are available in SuperWEB2. To specify which quantile ranges you want to be available, use an array of integers (greater than 1) separated by spaces and enclosed in square brackets. The order in which you list the integers in the array will be the order that the corresponding quantile ranges appear in the options in SuperWEB2.

For example:

cat Quantile Buckets [2 3 4 5 6 7 8 9 10]

cat Quantile Buckets [2 4 8]

This setting applies to SuperWEB2 only. You must restart Tomcat or the SuperWEB2 service for the change to take effect.

cat Quantile confidentialitystring <string>

Set the confidentiality string. This string is used to conceal the minimum of the bottom range and the maximum of the top range when quantile perturbation is enabled. For example:

cat Quantile confidentialitystring "*"

You are recommended not to change the confidentiality string except during the initial system configuration. If the string is changed then it may not be possible to reload some pre saved TXD files with recodes on the quantile.

Method Catalogue Settings

UsageDescription
cat [ <folder_id> ] findmethod <method_id>

Displays the IDs of all the datasets that the specified method is assigned to.

  • If you specify a folder ID, it searches only within that folder.
  • If you omit the folder ID, it searches the whole catalogue.

 SuperADMIN applies permissions to this command. It will only search datasets where you have at least read permission.

cat <dataset_id> methods
Displays a summary of the methods assigned to this dataset.
cat <dataset_id> methods details <method_id>
Displays detailed information about the specified method.
cat <dataset_id> addmethod <method_id> [ <priority> ]

Apply a method to the specified dataset.

The priority is optional. If you do not specify a priority then it defaults to the highest in the order and the method will be executed last.

cat <dataset_id> methods <method_id> priority <priority>
Change the priority of the specified method.
cat <dataset_id> removemethod <method_id>
Removes the specified method from this dataset.
cat <folder_id> removemethod <method_id>
Removes the specified method from all dataset in this folder.
cat <dataset_id> methods remove
Remove all methods from this dataset.
cat <dataset_id> disablemethods access {<user>|<group>} read {true|false}

Control whether or not users are allowed to disable mandatory methods in SuperCROSS. Set this to true to allow this or false otherwise.

cat <dataset_id> selectTableMethods access {<user>|<group>} read {true|false}
Control whether or not users are allowed to disable table methods in SuperCROSS. Set this to true to allow this or false otherwise.

Change Other Catalogue Settings

UsageDescription
cat <dataset_id> enablerecodetotals {true|false}

Enable or disable the ability for users to create recode totals. If you set this to false, then:

  • SuperCROSS users will not be able to select the Add Total With Default Recodes check box in the Fields window or add totals to recodes in the Define Recode window.
  • SuperWEB1 users will not be able to display recode totals.
cat <folder_id> maxfiles <value>
This setting is used by SuperWEB1 only. It does not apply to SuperWEB2.

Set the maximum number of files that can be saved into this folder. You can use this setting to prevent users from saving files to a particular folder, or to restrict the number of saved files to a reasonable limit.

For example:

cat user2 maxfiles 10

Set this to "-1" if you do not want to impose a limit on the number of files. When setting the value to -1 you must use quotes. For example:

cat user2 maxfiles "-1"

If you use this command without specifying a folder, then it will set the value at the root level. That value will be used as a default for all new folders as they are created. For example:

cat maxfiles "-1"
cat createpersonalfolder <user>

Create a personal folder accessible only to the specified user and the administrator. Personal folders are used in SuperWEB1.

Before issuing this command you must turn on the autofoldercreation setting first (using the gc command) if it is not already enabled. That setting configures SuperADMIN to automatically create personal folders when a user logs in to SuperWEB1. You can turn this feature off again after manually creating the folder if you wish.

For example, to create a personal folder for user2 and user3:

> gc autofoldersection autofoldercreation value "true"
> cat createpersonalfolder user2
Added folder 'user2' to folder 'Users'
> cat createpersonalfolder user3
Added folder 'user3' to folder 'Users'
> gc autofoldersection autofoldercreation value "false"
[ Folder : Users (id:Users) (Multilingual:false) (maxfiles:0) (files:0)]
    [ Folder : user2's Folder (id:user2) (Multilingual:false) (maxfiles:-1) (files:0)]
    [ Folder : user3's Folder (id:user3) (Multilingual:false) (maxfiles:-1) (files:0)]
cat <dataset_id> recordview [value {<user>|<group>}] {true|false}

Allow or deny access to the Record View feature in SuperWEB1, SuperWEB2, and SuperCROSS.

<id>
The ID of the dataset to apply the setting to.
value {<user>|<group>}

(Optional). The user or group this setting applies to. If you omit this then the setting will apply to all users and groups, unless specifically overridden for a particular user or group.

Please note that you cannot set Record View permissions for administrator users.

{true|false}
  • Set to true to allow Record View access.
  • Set to false to deny Record View access.

Click here to learn more about setting Record View permissions and see some examples.

cat <dataset_id> recordview value
Displays any user and group overrides set for this dataset.
cat <dataset_id> recordview value [{<user>|<group>}] reset

Remove any existing Record View setting override for the specified user or group.

If you do not specify a user or group, this command will remove all user and group overrides for this dataset (all users will revert to the dataset-level default setting).

cat <dataset_id> weightings {auto|client|server|off}
Change the type of weighting used for this dataset. See Understanding SuperSERVER, SuperCROSS and SuperWEB2 Weighting Differences for more details.