(MIC) COLLECT Command-Create Message Routing Definition

CA MIC Statements and Commands › (MIC) COLLECT Command-Create Message Routing Definition

(MIC) COLLECT Command-Create Message Routing Definition

You can manage cross-system message traffic by creating message routing definitions. Message routing definitions, or collection sets, are defined using the CA MIC COLLECT command. A collection set is identified by its local destination (unless the SETNAME parameter is also specified).

Each COLLECT command allows you to create, modify, replace, or delete a collection set. GCMF and ICMF use collection sets to control the routing of messages between systems.

The COLLECT command differs from the LINK command in that collection sets are used to route UNSOLICITED WTOs (such as tape mounts, job start and end messages, and printer messages). Linkages are used to issue cross-system commands and automatically receive command responses (SOLICITED WTOs). These responses are returned to the issuing system regardless of any collection sets defined.

Collection sets define the routing of unsolicited cross-system messages. The COLLECT command defines a collection set by identifying:

Types of messages that need to be imported to the local system
Systems from which the messages are to be imported
Local destination to which the imported messages are to be routed

Message selection criteria are quite flexible, as is the number of local destinations that can receive imported messages. As a result, you can create collection sets that are tailored to the requirements of your site. Some of the most common uses of collection sets are listed below:

Direct imported messages to all local consoles, individual local consoles, local products, or local TSO users
Record imported messages to the local SYSLOG
Direct messages from specific jobs to specific TSO users

Note: For more information, see the chapter “Advanced Topics” in the CA MIC Programming Guide.

Each collection set you create using the COLLECT command has a two-part name, consisting of the destination you specify (such as CONSOLE=SYSAMSTR) and the SETNAME value. Multiple collection sets can exist for the same destination only if you use the optional SETNAME operand on at least one of them. If you issue two or more COLLECT commands for the same collection set, then the first command creates the collection set by default, while all subsequent commands will modify the original collection set.

Note: The Local Destination for Collected Messages parameter is required when the COLLECT command is issued from the CA MIM parmlib. This parameter is not required when the COLLECT command is issued directly from a command source (for example, from a console, or from in an application).

Scope: Local

This command has the following format:

COLLECT Modifier	Collection Set Name	Local Destination for Collected Message	Message Inclusion/ Exclusion Criteria	From System Scope	Inclusion/Exclusion Filter
COLLECT [{ADD\| DELETE\| REPLACE}]	[SETNAME [={DEFAULT\| name}]]	[{CONSOLE=conname\| [DMONITOR[={ASIS\| JOBNAMES\| SESSIONS\| STATUS}] ]\| [DROUTCDE[={ASIS\| (codes)]]\| [PRODUCT=name]\| [SOURCE]\| [SYSLOG]\| [TSOUSER]}]	{ACTION\|NOACTION} {JOBNAME=(names)\| NOJOBNAME=(names)} {LOGONLY\|NOLOG} {MONITOR=([JOBNAMES] [SESSION] [STATUS])\| NOMONITOR=([JOBNAMES] [SESSIONS] [STATUS])} {MSGID=(msgids)\| NOMSGID=(msgids)} {ROUTCDE={ALL\|(codes)}\| NOROUTCDE={ALL\|(codes)} {WTOR\|NOWTOR}	[SYSID[={ALL\| ALLICMF\| ALLSYS\| EXTERNAL\| EXTSYS\| LOCAL\| sysid}]]	[{ALL\|ANY}]

COLLECT Modifier

Collection Set Name

Local Destination for Collected Message

Message Inclusion/

Exclusion Criteria

From System Scope

Inclusion/Exclusion Filter

COLLECT
   [{ADD|
    DELETE|
    REPLACE}]

[SETNAME
  [={DEFAULT|
     name}]]

[{CONSOLE=conname|
 [DMONITOR[={ASIS|
       JOBNAMES|
       SESSIONS|
       STATUS}] ]|
  [DROUTCDE[={ASIS|
       (codes)]]|
  [PRODUCT=name]|
  [SOURCE]|
  [SYSLOG]|
  [TSOUSER]}]

{ACTION|NOACTION}
{JOBNAME=(names)|
  NOJOBNAME=(names)}
{LOGONLY|NOLOG}
{MONITOR=([JOBNAMES]
          [SESSION]
          [STATUS])|
NOMONITOR=([JOBNAMES]
          [SESSIONS]
          [STATUS])}
{MSGID=(msgids)|
   NOMSGID=(msgids)}
{ROUTCDE={ALL|(codes)}|
  NOROUTCDE={ALL|(codes)}
{WTOR|NOWTOR}

[SYSID[={ALL|
     ALLICMF|
     ALLSYS|
     EXTERNAL|
     EXTSYS|
     LOCAL|
     sysid}]]

[{ALL|ANY}]

ACTION

Selects action type messages. By default, messages having descriptor codes 1, 2, 3, or 11 are considered action messages. Descriptor code 12 can also be specified as an action message. You can change this by using the SETOPTION ACTIONCODE command.

WTOR messages are not automatically considered action messages, although they are highlighted on the display. ACTION selects WTOR messages only if they have the descriptor code of an action message.

ADD: (Optional) This parameter creates a collection set if the one you are defining does not exist. Otherwise, CA MIC modifies the existing collection set. ADD is the default value.

ALL: Indicates that a message must meet the requirements of all inclusion operands in this collection set.

ANY

Indicates that a message must meet the requirements of any single inclusion operand in this collection set. When you create a new collection set, ANY is used by default. If you wish to use ALL to require that all inclusion operands be met, then you must specify it.

When modifying a collection set, the default (ANY or ALL) is the previously set value for that collection set. You can change ANY to ALL or ALL to ANY by explicitly specifying the new value on your collection set.

CONSOLE: Directs messages to a local console. Specify the console name. You can abbreviate this operand as CN.

DELETE: Deletes part of a collection set or the entire collection set, depending on what other operands you specify on this command.

DMONITOR

Broadcasts messages to consoles by matching the WTO monitor type of the message with the MCS monitor type of consoles. You can specify one or more of the following values on the DMONITOR parameter:

ASIS: Using MCS monitor types, this directs cross-system messages as though they are local messages. CA MIC directs cross-system TSO session messages to all local consoles receiving local TSO session messages. For example, cross-system job initiation messages go to local consoles receiving local job initiation messages.
JOBNAMES: Directs messages to consoles that are receiving job initiation, job termination, and unit record allocation monitor messages.
SESSION: Directs messages to consoles that are receiving TSO session initiation and termination monitor messages.
STATUS: Directs messages to consoles that are receiving monitor messages concerning data set dispositions.

Default: ASIS

You can specify any combination of the JOBNAMES, SESSION, and STATUS operands.

DROUTCDE

Broadcasts messages to consoles by matching the WTO routing code of the message with the MCS routing codes of consoles. You can specify one of the following values on the DROUTCDE operand:

ASIS: Directs messages to consoles by matching MCS routing codes on messages and on consoles. For example, routing code 3 messages from external systems are sent to local consoles receiving routing code 3 messages. Routing code 5 messages are sent to consoles receiving routing code 5 messages, and so on.
codes: Represents the routing codes of the consoles that should receive these messages. Specify a single routing code, a range of routing codes, or a list of routing codes in place of codes.

Default: ASIS

JOBNAME

Selects messages issued by designated jobs. Specify a single job name, a list of job names, or a range of job names (to a maximum of 20 job names).

You can use the * and # wildcard characters in a job name. See the Usage Notes for the COLLECT command.

LOGONLY

Selects messages destined only for the system log.

For information about using the CAPTURELOG operand to enable CA MIC to collect these message types, see (MIC) SETOPTION GCMF Command in this chapter.

MONITOR

Selects messages that have been assigned this monitor type. You can use the abbreviation MN for this operand. Specify one or more of the following values on the MONITOR operand:

JOBNAMES: Selects all job initiation, job termination, and unit record allocation monitor messages.
SESSION: Selects all TSO-session initiation and termination monitor messages.
STATUS: Selects all monitor messages regarding data set dispositions.

MSGID

Selects messages that have a designated message ID. Specify a single ID, a list of IDs, or a range of IDs (to a maximum of 20 IDs). Message IDs can be up to 12 characters long.

You can use the * and # wildcard characters in a message prefix. See the Usage Notes for the COLLECT command.

NOACTION: Excludes all action messages defined on the SETOPTION ACTIONCODE command.

NOJOBNAME

Excludes all messages issued by the designated jobs. Specify a single name, a list of names, or a range of names (to a maximum of 20 job names).

You can use the * and # wildcard characters in a job name. See the Usage Notes for the COLLECT command.

NOLOG: Excludes messages destined only for the system log.

NOMONITOR

Excludes monitor-type messages. You can specify NOMONITOR without any operands because it defaults to all types of monitor messages, or you can specify one or any combination of the following values:

JOBNAMES: Excludes all job initiation, job termination, and unit record allocation monitor messages.
SESSION: Excludes all TSO-session initiation and termination monitor messages.
STATUS: Excludes all monitor messages regarding data set dispositions.

NOMSGID

Excludes messages with the designated message IDs. Specify a single ID, a list of IDs, or a range of IDs (to a maximum of 20 IDs). Message IDs can be up to 12 characters long.

You can use the * and # wildcard characters, which are described in a message prefix. See the Usage Notes for the COLLECT command.

Note: NOMSGID and SETOPTION GCMF EXCLUDEPREFIX perform similar functions, but NOMSGID operates on a single collection set only. Also, NOMSGID handles 12-character messages, while EXCLUDEPREFIX handles 10-character messages.

NOROUTCDE

Excludes messages assigned this routing code. Specify one of these values on the NOROUTCDE operand:

ALL: Excludes all messages that have been assigned routing codes.
codes: Represents the routing codes that should be excluded. Specify a single code, a range of codes, or a list of codes.

NOWTOR: Excludes the echoing of all WTOR replies.

PRODUCT

Directs messages to local products. Currently, you can direct messages to CA Remote Console and CA OPS/MVS.

If you want to direct messages to CA Remote Console, then specify the CA Remote Console subsystem name of RCS in place of ssname. If you want to direct messages to CA OPS/MVS, then specify the OPS subsystem name of OPSS in place of ssname.

For example,

PRODUCT=RCS
PRODUCT=OPSS

Note for CA Remote Console Users: The subsystem name for CA Remote Console is identified on the CA Remote Console SSNAME parameter.

Note for CA OPS/MVS users: For more information, see CA OPS/MVS Considerations in the chapter “Advanced Topics” in the CA MIC Programming Guide.

REPLACE: Deletes an existing collection set and replaces it with the values created by this command. Unlike the DELETE operand, REPLACE effects the entire collection set.

ROUTCDE

Selects messages that have been assigned a routing code. Specify one of the following values on the ROUTCDE operand:

ALL: Selects all messages that have been assigned routing codes.
codes: Represents the routing codes that should be selected. Specify a single code, a range of codes, or a list of codes.

SETNAME

Assigns a name to a collection set. Specify one of these values on the SETNAME operand:

DEFAULT: Assigns the name DEFAULT to this collection set.
name: Represents the unique one- to eight-character name you want to use.

Default: SETNAME=DEFAULT

SOURCE: Directs messages to the current console (that is, the console from which you are issuing this command). SOURCE is the default value. This operand is not valid when COLLECT is issued from the MIMCMNDS or MIMSYNCH members.

SYSLOG: Directs messages to the local system log.

SYSID

Identifies systems from which you want to collect messages. Specify one of these values on the SYSID operand:

ALL: Identifies all systems in a CA MIM complex, including ICMF.
ALLICMF: Identifies all ICMF systems, excluding control file systems.
ALLSYS: Identifies all control file systems, excluding ICMF.
EXTERNAL: Identifies all systems except the local system, including ICMF. This is the default value.
EXTSYS: Identifies all control file systems except the local system, excluding ICMF.
LOCAL: Identifies the local system only.
sysid: Represents the ID of a system from which you want to collect messages (to a maximum of 32 IDs, or 128 IDs if using ICMF). You can use system names, aliases, or index numbers to identify these systems.

Default: SYSID=EXTERNAL

TSOUSER

Directs messages to a local TSO user. Specify the TSO ID of the user in place of userid.

Note: You can specify only one TSO user ID here.

WTOR: Selects all WTOR messages. Because most WTOR messages are assigned routing codes, you also can select WTOR messages by specifying ROUTCDE=ALL.

Usage Notes: COLLECT Command

The COLLECT command can be specified in the MIMCMNDS or MIMSYNCH member of the MIMPARMS data set. You also can issue this command from a console.
You must be authorized to issue system control commands (AUTH=SYS) to issue the COLLECT command. TSO users generally are not authorized to issue system control commands.
You can specify any number of the following operands (as long as they are not mutually exclusive):
- ACTION/NOACTION
- JOBNAME/NOJOBNAME
- LOGONLY/NOLOGONLY
- MONITOR/NOMONITOR
- MSGID/NOMSGID
- ROUTCDE/NOROUTCDE
- WTOR/NOWTOR
CA MIC looks at only the first ten characters of a message prefix and ignores the following characters:
- Any single preceding asterisk (*), plus (+), or at-sign (@) character
- All preceding blanks
CA MIC ignores the + and @ characters only when the operating system has inserted these characters. CA MIC accepts imbedded blanks if you specify the pound (#) character in that position.
You can use the following wildcard characters with the JOBNAME/NOJOBNAME and MSGID/NOMSGID operands:
*

Use the asterisk (*) wildcard character to exclude or include messages with a job name or message ID that matches the character string preceding the * character. The asterisk wildcard character can be specified only at the end of a character string, and only one asterisk can be specified per string. No additional characters can be specified after the asterisk.

For example, if you specify NOMSGID=IST*, then the collection set excludes any message with a message ID that begins with IST, no matter what the rest of the message ID is.

#

Use the pound (#) wildcard character to indicate a single character position that CA MIC should ignore when determining whether to exclude messages. The job name or message ID must be exactly the same length as the character string you specify. You can specify multiple pound sign wildcard characters in a character string.
Messages destined only for the system log are not displayed at active MCS consoles. Therefore, CA MIC does not check hardcopy-only type messages to determine whether they should be routed cross-system. To allow CA MIC to check these hardcopy-only messages, specify the command SETOPTION CAPTURELOG=YES. Once CAPTURELOG is activated, hardcopy message types can be collected for or excluded from external destinations by using the LOGONLY/NOLOGONLY operands on the COLLECT command.
You must define an ICMF system on an IDEFSYS command before you specify the ICMF ID of the system on the SYSID operand.

Examples: COLLECT Command

To collect messages from the job named TEST1 on system SYS1 and to direct those messages to the console from which this COLLECT command is being issued, issue this command:
```
COLLECT JOBNAME=TEST1 SYSID=SYS1
```
Suppose that the current console is receiving messages from an external system, and you want this console to start receiving messages from system 01 as well. To accomplish this task, issue this command:
```
COLLECT SYSID=01
```
To create a collection set that imports messages having route codes from external systems to the local copy of CA Remote Console, issue this command:
```
COLLECT PRODUCT=RCS SYSID=EXTERNAL ROUTCDE=ALL
```
To delete the collection set for the current console with a SETNAME of SET1, issue this command:
```
COLLECT DELETE SETNAME=SET1
```
To have the console CON1 collect messages from system SYS1, in addition to the systems it is currently collecting messages from, issue this command:
```
COLLECT CONSOLE=CON1 SYSID=SYS1
```