channel Command

[add|copy|modify|delete|print|list] channel NAME {CLAUSE};

• NAME is the name you assign to the channel. Channel names must be unique. For more information, see About Administrative Object Names.
• CLAUSEs provides additional information about the channel.

add channel NAME [user USER_NAME] [ADD_ITEM {ADD_ITEM}];

• NAME is the name of the channel you are defining. Channel names cannot include asterisks.

  You cannot have both a channel and a portal with the same name.

• user USER_NAME can be included if you are a business administrator with person/group/role access defining a channel for another user. This user is the item’s “owner.” If the User clause is not included, the channel is a system item.
• ADD_ITEM provides additional information about the channel. The add channel clauses are:

  description VALUE

  icon FILENAME

  label VALUE

  href VALUE

  alt VALUE

  height VALUE

  command NAME {,NAME}

  setting NAME [STRING]

  webreport NAME [user USER_NAME]

  dataobject NAME [user USER_NAME]

  visible USER_NAME{,USER_NAME};

  [!|not]hidden

  property NAME [to ADMINTYPE NAME] [value STRING]

  history STRING

Label Clause

This clause specifies the label to appear in the application in which the channel is assigned.

Href Clause

This clause is used to provide link data to the JSP. The Href link is evaluated to bring up another page. Many channels will not have an Href value at all. However, channels designed for the “tree” channels require an Href because the root node of the tree causes a new page to be displayed when clicked. The Href string generally includes a fully-qualified JSP filename and parameters, which can contain embedded macros and expressions for mapping to database schema. For more information, see MQL Concepts: Using Macros and Expressions in Configurable Components.

The syntax is:

• VALUE is the link data.

Alt Clause

This clause is used to define text that is displayed until any image associated with the channel is displayed and also as “mouse over text.”

The syntax is:

alt VALUE;

• VALUE is the text that is displayed.

For example, you could use the following for a Tools channel:

alt “Tasks”;

Height Clause

This clause is used to indicate the height size in pixels the channel will occupy on the page. The default and minimum allowed is 260. The syntax is:

height VALUE;

• VALUE is the size in pixels. If you enter a value less than 260, 260 will be used.

Command Clause

This clause is used to specify existing commands to be added to the channel you are creating. Each command will be a separate tab in the channel and displayed in the order in which they are added. Separate items with a comma.

The syntax is:

command NAME{,NAME};

• NAME is the name of the command you are adding.

For more information, see Add Command.

Setting Clause

This clause provides any name/value pairs that the channel needs. They can be used by JSP code, but not by hrefs on the Link tab. For more information, see MQL Concepts: Using Macros and Expressions in Configurable Components.

The syntax is:

setting NAME [STRING];

Dataobject Clause

This clause can be used to add dataobjects to a channel. A dataobject can be used to personalize a channel.The syntax is:

dataobject NAME [USER_NAME];

Visible Clause

This clause specifies other existing users who can read the channel with MQL list, print, and evaluate commands. The MQL copy channel command can be used to copy any visible channel to your own workspace.

The syntax is:

visible USER_NAME{,USER_NAME};

Separate users with a comma, but no space.

History Clause

The history keyword adds a history record marked “custom” to the channel that is being added. The STRING argument is a free-text string that allows you to enter some information describing the nature of the addition. For more information, see Adding History to Administrative Objects.

A Business Administrator with channel access, can copy system channels. A Business Administrator with person access, can copy channels in any person’s workspace (likewise for groups and roles). Other users can copy visible workspace channels to their own workspaces.

This command lets you duplicate channel definitions with the option to change the value of clause arguments:

copy channel SRC_NAME DST_NAME [COPY_ITEM {COPY_ITEM}] [MOD_ITEM {MOD_ITEM}];

• SRC_NAME is the name of the channel definition (source) to be copied.
• DST_NAME is the name of the new definition (destination).
• COPY_ITEM can be:

  Clause	Description
  fromuser USERNAME	USERNAME is the name of a person, group, role or association.
  touser USERNAME
  overwrite	Replaces any channel of the same name belonging to the user specified in the touser clause.
  history STRING	Adds a history record marked "custom" to the channel that is being copied. The STRING argument is a free-text string that allows you to enter some information describing the nature of the copy operation. For more information, see Adding History to Administrative Objects.

  The order of the fromuser, touser, and overwrite clauses is irrelevant, but MOD_ITEMs, if included, must come last.

• MOD_ITEM is modifications that you can make to the new definition. Refer to the table below for a complete list of possible modifications. You only need to specify the fields to be modified.

  Modify Channel Clause	Specifies
  name NEW_NAME	The current channel name is changed to the new name entered.
  description VALUE	The current description value, if any, is set to the value entered.
  icon FILENAME	The image is changed to the new image in the file specified.
  label VALUE	The label is changed to the new value specified.
  href VALUE	The link data information is changed to the new value specified.
  alt VALUE	The alternate text is changed to the new value specified.
  height VALUE	The height is changed to the new value specified.
  [fromuser FROMUSER] touser TOUSER	For use with copy only. The current channel is owned by FROMUSER, and copied to TOUSER. If not specified, it is assumed to be current context user.
  place COMMAND1 before COMMAND2	The named COMMAND1 is moved or added before COMMAND2. If COMMAND2 is an empty string, COMMAND1 is placed before all commands in the channel.
  place COMMAND1 after COMMAND2	The named COMMAND1 is moved or added after COMMAND2. If COMMAND2 is an empty string, COMMAND1 is placed after all commands in the channel.
  add setting NAME [STRING]	The named setting and STRING are added to the channel.
  place dataobject NAME1 [user USER] before NAME2 [user USER]	The named dataobject is moved or added before dataobject NAME2. If NAME2 is an empty string, NAME1 is placed before all dataobjects in the channel.
  place dataobject NAME1 [user USER] after NAME2 [user USER]	The named dataobject is moved or added after NAME2. If NAME2 is an empty string, NAME1 is placed after all dataobjects in the channel.
  place webreport NAME1 [user USER] before NAME2 [user USER]	The named webreport is moved or added before webreport NAME2. If NAME2 is an empty string, NAME1 is placed before all dataobjects in the channel.
  place webreport NAME1 [user USER] after NAME2 [user USER]	The named webreport is moved or added after NAME2. If NAME2 is an empty string, NAME1 is placed after all webreports in the channel.
  remove dataobject NAME [user USER]	The named dataobject is removed from the channel.
  remove webreport NAME [user USER]	The named webreport is removed from the channel.
  remove command NAME	The named command is removed from the channel.
  remove setting NAME [STRING]	The named setting and STRING are removed from the channel.
  visible USER_NAME{,USER_NAME};	The named user(s) have visibility to the channel. For more information,
  property NAME [to ADMINTYPE NAME] [value STRING]	The named property is modified.
  add property NAME [to ADMINTYPE NAME] [value STRING]	The named property is added.
  remove property NAME [to ADMINTYPE NAME] [value STRING]	The named property is removed.
  history STRING	The history keyword adds a history record marked "custom" to the channel that is being copied. The STRING argument is a free-text string that allows you to enter some information describing the nature of the copy operation. For more information, see Adding History to Administrative Objects.

You must be a business administrator with group or role access to modify a channel owned by a group or role.

Use the Modify channel command to add or remove defining clauses or change the value of clause arguments:

 modify channel NAME [user USER_NAME][MOD_ITEM {MOD_ITEM}];

• NAME is the name of the channel you want to modify. If you are a business administrator with person access, you can include the User clause to indicate another user’s workspace object.
• MOD_ITEM is any of the items in the table above.

Each modification clause is related to the arguments that define the channel. To change the value of one of the defining clauses or add a new one, use the Modify clause that corresponds to the desired change.

When modifying a channel, you can make the changes from a script or while working interactively with MQL.

• If working interactively, perform one or two changes at a time to avoid the possibility of one invalid clause invalidating the entire command.
• If working from a script, group the changes together in a single modify channel command.

History Clause

The history keyword adds a history record marked “custom” to the channel that is being modified. The STRING argument is a free-text string that allows you to enter some information describing the nature of the modification. For more information, see Adding History to Administrative Objects.

You must be a business administrator with group or role access to delete a channel owned by a group or role.

If a channel is no longer required, you can delete it using the Delete channel command:

delete channel NAME [user USER_NAME];

• NAME is the name of the channel to be deleted. If you are a business administrator with person access, you can include the user clause to indicate another user’s workspace object.

Searches the list of defined channels. If the name is found, that channel is deleted. If the name is not found, an error message is displayed. For example, to delete the channel named “Toolbar” enter the following:

delete channel "Toolbar";

After this command is processed, the channel is deleted and you receive an MQL prompt for another command.