Conditional Requests and Selection Criteria

Many services can be conditionally executed based on various terms and conditions. This topic describes in more detail the various criteria that can be used.

Poor usage of selection criteria can dramatically impact the overall performance. Before using such selection criteria, read Performance Considerations for Selection Criteria.

The full syntax for the selection criteria is as follows:

[IF] {[MEM=memname*] | [GROUP|GRP=group_name*] | [TABLE|TBL=table_name*] |

[JOB=job_name*] | [JOBID=jes_job_number] |

[OWNER=owner*] | [OID=orderid] | [ODATE={ODAT|date}] |

[RECTYPE={JOB|TAB|ALL}] |

[STATUS={WAIT_SCH | WAIT_TIME | WAIT_CONF | WAIT_PIPE | WAIT_ORD | EXEC_ERR | EXEC_WSUB | EXEC_INQ | EXEC_NJE | END_OK | END_OK_FOK | END_NOK_ABND | END_NOK_JCLE | END_NOK_UNKW | END_NOK_CC | END_NOK_NSUB | END_NOK_DISA | ENDED | NOT_ENDED | EXIST | NOTEXIST | NOT_DELETED | DEL} ] |

[STATE={HOLD|FREE}]}

[{AND|OR} selection2 }]...

Parameters marked with an * (asterisk) to the right of the field value are used as a prefix for the specified selection criteria. No masking is allowed in any other field.

For example, MEM=ABC* means select jobs whose MEMNAME prefix is "ABC". Coding MEM=* is the equivalent of omitting the MEM selection criteria, that is, all MEMNAMEs are eligible for selection.

Note that the same parameters can be used as Selection Criteria or IF statement Criteria, but their functionality differs.

• Selection Criteria: Used to select all jobs on the AJF to be acted upon.
• IF Criteria: Used to determine if any action will be taken. If any job on the AJF matches the IF criteria, the action is taken.

  Table 282 Selection and IF statement Criteria Parameters

  Parameter	Description
  OFORMAT	(For Search function only) Determines which fields are displayed in the CTMAPI search output. Valid values are: 0 - Standard format. Default. Fields displayed: JOB, ORDERID, STATUS, ODATE, JOBID 1 - Extended format. Fields displayed: MEMNAME, SCHDTAB, SCHDLIB, JOBNAME, OWNER, ODATE, TASK TYPE, GROUP, ORDERID, JOBID, STATUS, JOB STATE
  MEM	Member name of the job
  GROUP|GRP	Group name of the job
  TABLE|TBL	Table name of the job
  JOB	Job name of the job (valid only after the job was submitted)
  JOBID	JES job number (valid only after the job was submitted)
  OWNER	Owner of the job
  OID	The Control-M Order ID of the job
  ODATE	The ODATE of the job. Valid values are: ODATE or DATE – The current Control-M ODATE date – The date, in the format YYMMDD, MMDDYY, or DDMMYY, depending on your site format
  RECTYPE	The RECTYPE (record type) parameter determines whether the AJF action (such as HOLD) is performed on SMART tables, regular jobs, or both. Valid values are: RECTYPE=JOB- performs the action only on regular jobs RECTYPE=TAB- performs the action only on SMART tables RECTYPE=ALL- performs the action on SMART tables and regular jobs. Default.
  STATUS	For an explanation of these statuses, see Table 288 in Status Return Codes.
  STATE	Whether the job is held or free. Valid values are: HOLD – The job is held. FREE – The job is free.
  AND|OR	Boolean logic connectors, valid only in the IF statement. The AND connector is implicit and need not be coded. When using Boolean connectors it is best to enclose the criteria parameters in parentheses to ensure that the criteria expressions are evaluated in the intended order.
  selection2	Any of the above parameters.

Note: the same keyword parameter may not appear more than once, even with different values, in the selection criteria list, but may appear multiple times in the IF statement criteria.

The processing logic of the statement

ctmapi-command action {list of selection-criteria} IF {list of if-criteria}

is as follows:

CTMAPI first finds all jobs on the AJF which match the Selection Criteria. It then determines if any job on the AJF matches the IF Criteria. If even one job on the AJF matches the IF criteria, then EVERY job which matched the Selection Criteria is acted upon by the command action; otherwise the action is not performed (Reason 220 in message IOA723I) and the utility ends with a return code of 4.

If there is no IF clause then CTMAPI simply acts on all the jobs satisfying the selection-criteria unconditionally.

Example 1

AJF CONFIRM MEM=YOURJOB* IF MEM=MYJOB STATUS=END_OK

The above command checks the AJF to determine if any job, MYJOB, has ended OK. If at least one has, then all jobs beginning with the name YOURJOB will be confirmed, if they are waiting confirmation. Any YOURJOB job, which is not waiting confirmation will have no action taken on it (and an error message will be produced making note of this, but the message can effectively be ignored).

Example 2

AJF DELETE GRP=MYGRP OWNER=MYUSER IF (STATUS=WAIT_SCH OR STATE=HOLD) AND MEM=MYJOB

The above command checks the AJF to determine if any job, MYJOB, is in Wait Schedule status or is being Held. If at least one is, then all jobs with group name MYGRP and owner name MYUSER will be deleted, if they are being held. Any selected job, which is not being held will have no action taken on it (and an error message will be produced making note of this) since the DELETE action operates only on held jobs.