EVENT SERVICES CREATE Command Format

The EVENT SERVICES CREATE command enables you to create a new request for event data and define which data is sent to your application. The EVENT SERVICES CREATE command uses the following format and parameters:

Command Parameters
EVENT [SERVICES] CREATE ID=event-request-name
WHERE (CCODE | PNAME | PNUMber | STARTT | STOPT | USER | SNODE | TYPE | FNAME | CASE | LASTSEQ | MAXQCNT | EXIT)
ORWHERE | =(CCODE | PNAME | PNUMber | USER | SNODE | TYPE | FNAME)

Required Parameters

The EVENT SERVICES CREATE command has two required parameters.

ID=event-request-name
specifies a logical name for the event services request. This name is a text string of 1–16 characters. You can use any printable characters. You cannot use embedded blanks.
WHERE (CCODE = (condition, completion code) | PNAME = name | (list)
PNUMber = number | (list)
STARTT = ([date | day] [,hh:mm:ssXM])
STOPT = ([date | day] [,hh:mm:ssXM])
USER = name | (list)
SNODE = name | (list)
TYPE = id | (list)
FNAME = dsname | (list)
CASE = YES | NO
LASTSEQ=n
MXQCNT=n
EXIT=exitname)

specifies selection criteria for event records.

You must specify at least one WHERE () subparameter, such as CCODE, PNAME, PNUMBER, or TYPE.
CCODE = (condition, completion code)

specifies selection by completion code.

condition specifies a relationship to the completion code given in the subsequent positional parameter. The options for specifying condition are:

GT greater than LT less than EQ equal to NE not equal to GE greater than or equal to LE less than or equal to

completion specifies a completion code value ranging from 1 to 2,147,483,647 so the RUN TASK can pass all values.

For example, if you specify CCODE = (GT,0), you see event records in which the step completion code is greater than zero, as long as the records also meet other specified criteria.

PNAME = name | (list)

specifies selection by Process name. Specify a list of Processes by enclosing them in parentheses. You can use a wild card character (*) at the end of the name.

For example, if you specify PNAME=TEST*, then all records with TEST in the first four characters of the Process name field are selected. Records having TEST, TEST123, and TESTX all satisfy the selection criterion.

name specifies the name of the Process to select.

(list) specifies a list of Process names to select. Enclose the list in parentheses. Separate Processes in the list with commas.

PNUMber = number | (list)

specifies selection by Process number. To request a list of Processes, enclose them in parentheses. The range is 1–99999.

number specifies the number of the Process to select.

STARTT = ([date | day] [,hh:mm:ssXM])

specifies selection by start date and time. Specify STARTT as a date and time prior to the current time. If you set this parameter, the event records retrieved from the statistics file begin with the date and time you specified and continue until the current time is reached. At that point, event records are processed as they occur.

Note: If you specify STARTT and LASTSEQ with the EVENT SERVICES START command, those values replace the values specified for these parameters in the EVENT SERVICES CREATE command. When you use the time specification in conjunction with the LASTSEQ parameter, you must include hours, minutes, seconds, and hundredths of seconds in the format hh:mm:ss.th.

date specifies the starting date from which event records are retrieved from the statistics file. You can specify the date in either Gregorian or Julian format.

If you use a Gregorian date format, set the DATEFORM initialization parameter to the appropriate date format. Otherwise, the date format defaults to the platform date format. You do not need to set the DATEFORM parameter for Julian date format.

The following table shows the acceptable date formats:

Format DATEFORM Parameter Date Format
Gregorian DATEFORM=MDY mmddyy or mmddyyyy

mm/dd/yy or mm/dd/yyyy

mm.dd.yy or mm.dd.yyyy

Gregorian DATEFORM=DMY ddmmyy or ddmmyyyy

dd/mm/yy or dd/mm/yyyy

dd.mm.yy or dd.mm.yyyy

Gregorian DATEFORM=YMD yymmdd or yyyymmdd

yy/mm/dd or yyyy/mm/dd

yy.mm.dd or yyyy.mm.dd

Gregorian DATEFORM=YDM yyddmm or yyyyddmm

yy/dd/mm or yyyy/dd/mm

yy.dd.mm or yyyy.dd.mm

Julian N/A yyddd or yyyyddd

yy/ddd or yyyy/ddd

yy.ddd or yyyy.ddd

Note: If RETAIN=Y, you cannot specify a date in the STARTT parameter of the initialization file.

day specifies the day of the week to select. Valid names include MOnday, TUesday, WEdnesday, THursday, FRiday, SAturday, and SUnday. You can also specify YESTER to retrieve event records created since yesterday, or TODAY to retrieve event records created today.

hh:mm:ssXM indicates the start time of day in hours (hh), minutes (mm), and seconds (ss) selected. XM indicates AM or PM. You can use the 24-hour clock or the 12-hour clock. If you use the 24-hour clock, valid times are 00:00-24:00. If you use the 12-hour clock, valid times are 00:00-12:00 and you must indicate AM or PM. For example, 01:00 hours on the 24 hour clock is expressed as 1:00AM on the 12 hour clock. If you do not specify AM or PM, IBM® Connect:Direct® assumes the 24-hour clock. You do not need to specify minutes and seconds. You can also specify NOON to retrieve event records starting at noon, or MIDNIGHT to retrieve event records starting at midnight. The default for the time is 00:00:00, the beginning of the day.

If you do not specify the STARTT parameter, event processing begins with the current time.

STOPT = ([date | day] [,hh:mm:ssXM])

specifies when interest in event data ends.

date specifies the stop date when event processing ends. You can specify the date in either Gregorian or Julian format.

Refer to the STARTT subparameter for a discussion of Gregorian and Julian date formats.

If you specify only the date, the time defaults to 24:00:00.

day specifies the day of the week to select. Valid values include MOnday, TUesday, WEdnesday, THursday, FRiday, SAturday, and SUnday. You can also specify TODAY.

hh:mm:ssXM indicates the stop time of day in hours (hh), minutes (mm), and seconds (ss) to select. XM indicates AM or PM. You can use the 24-hour clock or the 12-hour clock. If you use the 24-hour clock, valid times are 00:00-24:00. If you use the 12-hour clock, valid times are 00:00-12:00 and you must indicate AM or PM. For example, 01:00 hours on the 24 hour clock is expressed as 1:00AM on the 12 hour clock. If you do not specify AM or PM, IBM Connect:Direct assumes the 24-hour clock.

You do not need to specify minutes and seconds. You can also specify NOON to retrieve event records starting at noon, or MIDNIGHT to retrieve event records starting at midnight. The default time is 24:00:00, the end of the day.

If you do not specify the STOPT parameter, you must issue an EVENT SERVICES STOP command to stop event processing.

USER = name | (list)

limits the selected event records to those written for userids with the specified name. You can specify a list of names by enclosing them in parentheses. You can use wild card characters. For example, if you specify USER = SYS$*, then records with SYS$ in the first four characters of the userid field are selected. Records having SYS$BOB, SYS$ADM, and SYS$0001 all satisfy this selection criterion. Userid names can be up to 64 characters in length and can contain lowercase characters.

name specifies the userid to select.

(list) specifies a list of userids to select. Enclose the list in parentheses. Separate userids in the list with commas.

SNODE = name | (list)

limits the selected event records to those written for Processes where the specified node name acted as SNODE. You can specify a list of names by enclosing them in parentheses. You can use wild card characters. For example, if you specify SNODE=DALLAS*, then all records with DALLAS in the first six characters of the SNODE field are selected. Records having DALLAS.PROD, DALLAS.TEST, and DALLAS all satisfy this selection criterion. SNODE names can contain lowercase characters.

name specifies the SNODE to select.

(list) specifies a list of SNODES to select. Enclose the list in parentheses. Separate SNODES in the list with commas.

TYPE = id | (list)

specifies the event record types to select. Every event record that IBM Connect:Direct generates has an associated record-type identifier. Each identifier is two characters long and indicates the event or function that generated the record. The identifier also indicates the record format and contents.

id specifies the event record type.

(list) specifies a list of event record types to select. Enclose the list in parentheses. Separate record types in the list with commas.

FNAME=dsname | (list)

limits the selected event records to those that contain the specified filename. The FNAME subparameter is valid for the following record types: Copy Termination (CT), Run Job (RJ), Start IBM Connect:Direct (SD), and Submit within Process (SW).

name specifies the filename to select.

(list) specifies a list of filenames to select. Enclose the list in parentheses. Separate filenames in the list with commas.

The meaning of the filename within these records is unique for each record type. For example, the Run Job record contains the filename of the submitted JCL. Filenames can be up to 254 characters in length and can contain lowercase characters. Filenames must conform to your platform's naming conventions.

CASE=YES | NO

specifies whether lowercase or mixed-case data is permitted for the USER, SNODE, and FNAME subparameters. The CASE subparameter overrides the global CASE option defined at signon for the SELECT STATISTICS command.

YES changes the data in USER, SNODE, and FNAME to uppercase regardless of the actual data specified.

NO preserves the actual case entered for the USER, SNODE, and FNAME subparameters.

The CASE defaults to the setting defined in the session defaults, if nothing is specified.

LASTSEQ=n

specifies the last sequence number (for Restart capability) associated with the date/time stamp. Use it with the STARTT parameter. This information is provided by CICS when you issue a CREATE EVENT SERVICES REQUEST command for an event services request that finished abnormally.

MAXQCNT=n

specifies the maximum number of elements that can reside in the internal event queue for this request. All events that match the WHERE criteria for this request are placed on an internal queue. If events occur faster than the API can process them, the queue can become full. If the queue becomes full, IBM Connect:Direct terminates event services requests. You can modify the queue size using MAXQCNT. Each queue element takes approximately 2K in storage. The default is 100.

EXIT=exitname

specifies the name of an EVENT SERVICES OPTION exit. The sample exit DGAXEV01 is provided in the sample library. Event data is processed by an exit rather than the calling API, if EXIT is specified.

Optional Parameters

The following parameters are optional for the EVENT SERVICES CREATE command.

ORWHERE (CCODE = (condition, completion code) | PNAME = name | (list)
PNUMber = number | (list)
USER = name | (list)
SNODE = name | (list)
TYPE = id | (list)
FNAME = dsname | (list)

specifies which statistics records you want to examine.

The subparameters, such as CCODE, PNAME, PNUMBER, and TYPE, are optional, but you must specify at least one.

The parameters for the ORWHERE keyword are defined in the WHERE keyword section.

Sample Command

The following is an example of the EVENT SERVICES CREATE command.

EVENT CREATE ID=PROCESS_TERM WHERE(TYPE=PT)