GET_CONSOLE, GET_EVENT_INFO

ScriptEigener Objekttyp in der Automation Engine Function: Reads values of occurred Console, FileSystem and Database events.

Syntax

GET_CONSOLE(Keyword, [Index])
GET_EVENT_INFO(Keyword, [Index])

Syntax	Description/Format
Keyword	Specifies the message part which should be read Format: AE name, script literal or script variable The table shown below explains the keywords for the individual platforms:
Index	Can only be used in combination with the keyword INSERT, RESULT1 and RESULT2. Format: script literal, number or script variable. Default value: 1 For INSERT: Access to the 16-bit fields of an z/OS console message and access to the message text's variable part (insert) of an OS/400 message. For RESULT1 and RESULT2: Column number of the SQL query (database event)

Syntax

Description/Format

Keyword

Specifies the message part which should be read
Format: AE name, script literal or script variable

The table shown below explains the keywords for the individual platforms:

Index

Can only be used in combination with the keyword INSERT, RESULT1 and RESULT2.

Format: script literal, number or script variable. Default value: 1

For INSERT:

Access to the 16-bit fields of an z/OS console message and access to the message text's variable part (insert) of an OS/400 message.

For RESULT1 and RESULT2:

Column number of the SQL query (database event)

Keywords

Keyword	Console BS2000	Console z/OS	Console OS/400	Console SAP (ABAP)	Console SAP (XI)	Console SAP (Java)	Console Windows	File system	File system automatically z/OS	Database
ACCESS
ACTIVATIONSTATE
ALERT_OPTION
CATEGORY
CHANNEL
DDNAME
EVENT_ADDITIONAL_PARM
EVENT_COUNTOFJOBS
EVENT_GUID
EVENT_ID
EVENT_PARM
EVENT_PROCESSSTATE
EVENT_SERVER
EVENT_STATE
EVENT_TYPE
FILENAME
FILESIZE
ID
INFO_ACTION
INFO_TEXT
INSERT
INSERT_COUNT
JOB_ABENDED
JOB_ENDED
JOB_ID
JOB_NAME
LPAR_NAME
MEMGEN
MSG_DESCRIPTOR
MSG_FILE_LIBRARY
MSG_FILENAME
MSG_ID
MSG_KEY
MSG_LEVEL
MSG_LIBRARY_USED
MSG_MISC
MSG_SEVERITY
MSG_TEXT
MSGNR
MSGTYPE, MSGTYP
OS_NAME
PARTY
PROCESSID
PROGRAM_NAME
REPLY_ID
RESULT
RESULT1
RESULT2
RETCODE
RETCODE_STATE
SEND_JOB
SEND_JOB_NUMBER
SEND_USER_PROFILE
SERVICE
SMS_MANAGEMENT_CLASS SMS_DATA_CLASS SMS_STORAGE_CLASS
SOURCE
STATE
STEP_NAME
SYS_NAME
SYSPLEX_NAME
TIMESTAMP
TYPE
USER

Note that the keys listed in the "FileSystem" column can only be used in FileSystem events with the setting "Check" equals "FILE_SIZE" or "empty" (with or without a combination of "FILE_STABLE" or "FILE_CHANGED") and "PATH_FILE_COUNT" (only in combination with "FILE_STABLE" or "FILE_CHANGED").

Description

Keyword	Description
ACCESS	File access Allowed value: "CLOSE" - closes the file
ACTIVATIONSTATE	Adapter status Allowed values: "STARTED" and "STOPPED"
ALERT_OPTION	Returns if and when an SNA alert is created and sent to the message Allowed values: "DEFER" - An alert is sent after local problem analysis "IMMED" - An alert is sent immediately when the message is sent. For the message queue, the attribute permitting alerts must be set to "YES" "NO" - No alert is sent "UNATTEND" - An alert is only sent if the system runs in non-monitored mode. The alarm status network attribute (ALRSTS) is "UNATTEND".
CATEGORY	Event category
CHANNEL	Communication channel
DDNAME	DD description
EVENT_ADDITIONAL_PARM	Additional parameters of SAP Java Scheduler events
EVENT_COUNTOFJOBS	Number of triggered SAP jobs (ABAP)
EVENT_GUID	SAP event's instance number (ABAP)
EVENT_ID	Event ID (ABAP/Java Events)
EVENT_PARM	SAP event parameter (ABAP/Java events)
EVENT_PROCESSSTATE	SAP processing status (ABAP)
EVENT_SERVER	SAP-event server (ABAP)
EVENT_STATE	SAP event status (ABAP)
EVENT_TYPE	SAP Java Scheduler event type
FILENAME	Name of the file In File-System events with wildcards, the following value is returned as a file name: ALL - If the option "Consider all files" has been activated. ONE - If the option "Consider all files" has been deactivated.
FILESIZE	Size of the file
ID	Message ID
INFO_ACTION	Action Allowed values: "Y" and "N" "Y" - An object has been activated "N" - No object has been activated
INFO_TEXT	Name of the activated object
INSERT	Accesses a certain variable part of a message together with Index
INSERT_COUNT	Determines the number of the message's variable part
JOB_ABENDED	End status of the job which closed the file Allowed values: "Y" and "N" "Y" - The job ended abnormally "N" - The job ended normally
JOB_ENDED	StatusZustand einer Aufgabe (z.B. aktiv, blockiert, in Generierung, usw.). of the job which closed the file Allowed values: "Y" and "N" "Y" - The job has already ended "N" - The job is still running
JOB_ID	Identification name of the job
LPAR_NAME	Returns the LPAR name
JOB_NAME	Name of the job
MEMGEN	Member name or generation number
MSG_DESCRIPTOR	Description of the message as a 16-bit field Bit 01(corresponds to X'80') = SYSTEM_FAILURE - system failure Bit 02 (corresponds to X'40') = IMMEDIATE_ACTION - immediate action required Bit 03 (corresponds to X'20') = EVENTUAL_ACTION - eventual action required Bit 04 (corresponds to X'10') = SYSTEM_STATUS - system status Bit 05 (corresponds to X'08') = IMMEDIATE_COMMAND - immediate command response Bit 06 (corresponds to X'04') = JOB_STATUS - job status Bit 07 (corresponds to X'02') = APPLICATION - application program/processor Bit 08 (corresponds to X'01') = OUT_OF_LINE - out of line Bit 09 (corresponds to X'80') = OPERATOR_REQUEST - operator's request Bit 10 (corresponds to X'40') = TRACK_COMMAND_R - track command response Bit 11 (corresponds to X'20') = CRITICAL_ACTION - critical eventual action Bit 12 (corresponds to X'10') = IMPORTANT_INFO - important information Bit 13 (corresponds to X'08') = PREVIOUSLY_AUTO - previously automated Bit 14 (corresponds to X'04') - reserved Bit 15 (corresponds to X'02') - reserved Bit 16 (corresponds to X'01') - reserved
MSG_FILE_LIBRARY	Name of the library containing the message file or the values "CURLIB" or "LIBL" used by the send program
MSG_FILENAME	Name of the message file which contains the obtained message
MSG_ID	Message key of the of the obtained message This field is left blank if an improvised message is obtained
MSG_KEY	Message key of the obtained message Four-figure value in hexadecimal format X'xxxxxxxx'
MSG_LEVEL	Urgency level of the message (16-bit field). Bit 01(corresponds to X'80') = WTOR - WTOR Bit 02 (corresponds to X'40') = IMMEDIATE_ACTION - immediate action Bit 03 (corresponds to X'20') = CRITICAL_ACTION - critical eventual action Bit 04 (corresponds to X'10') = EVENTUAL_ACTION - eventual action required Bit 05 (corresponds to X'08') = INFO - informational Bit 06 (corresponds to X'04') = BROADCAST Bit 07 (corresponds to X'02') - reserved Bit 08 (corresponds to X'01') - reserved Bit 09 (corresponds to X'80') - reserved Bit 10 (corresponds to X'40') - reserved Bit 11 (corresponds to X'20') - reserved Bit 12 (corresponds to X'10') - reserved Bit 13 (corresponds to X'08') - reserved Bit 14 (corresponds to X'04') - reserved Bit 15 (corresponds to X'02') - reserved Bit 16 (corresponds to X'01') - reserved
MSG_LIBRARY_USED	Real name of the library which is used to send the message The library can contain overriding instructions. Thus, this is not necessarily the library in which the message is actually stored
MSG_MISC	Miscellaneous message information (16-bit field). Bit 01(corresponds to X'80') = DISPLAY_UD_MSG - display UD messages Bit 02 (corresponds to X'40') = DISPLAY_ONLY_UD_MSG - display only UD messages Bit 03 (corresponds to X'20') = QUEUE_BY_ID_ONLY - queue by id only Bit 04 (corresponds to X'10') = QUEUE_BY_AUTO - queue by automation Bit 05 (corresponds to X'08') = QUEUE_BY_HARDCOPY - queue by hard copy Bit 06 (corresponds to X'04') - reserved Bit 07 (corresponds to X'02') - reserved Bit 08 (corresponds to X'01') - reserved Bit 09 (corresponds to X'80') = ECHO_OPERATOR_CMD - echo operator command Bit 10 (corresponds to X'40') = ECHO_INTERNAL_CMD - echo internal command Bit 11 (corresponds to X'20') = RESULT_OF_WTL_MACRO - result of wtl macro Bit 12 (corresponds to X'10') - reserved Bit 13 (corresponds to X'08') - reserved Bit 14 (corresponds to X'04') - reserved Bit 15 (corresponds to X'02') - reserved Bit 16 (corresponds to X'01') - reserved
MSG_SEVERITY	Severity of the obtained message Allowed values: "0" to "99"
MSG_TEXT	Message text (default value)
MSGNR	Message number
MSGTYPE, MSGTYP	Message type Allowed values especially for OS/400: "01" - Completion "02" - Diagnostic "04" - Informational "05" - Inquiry "06" - Sender's copy "08" - Request "10" - Request with prompting "14" - Notify (handled exception) "15" - Escape (handled exception) "16" - Notify (unhandled exception) "17" - Escape (unhandled exception) "21" - Reply, not validity checked "22" - Reply, validity checked "23" - Reply, message default used "24" - Reply, system default used "25" - Reply, from system reply list
OS_NAME	Name of the operating system in the console message defined by IBM. Currently always "MVS"
PARTY	Partner
PROCESSID	Task number (TSN) in the console message
PROGRAM_NAME	Program description
REPLY_ID	Reply ID of the console message.
RESULT	Indicates whether the conditions of FileSystem events with the checks FILESIZE or PATH_FILE_COUNT were fulfilled. Allowed values: "Y" and "N" "Y" - The condition was fulfilled "N" -The condition was not fulfilled
RESULT1 RESULT2	RESULT1 allows access to the SQL query result for "Value 1", RESULT2 to the result for "Value 2". In index specify the column number whose value should be read. Note that a database event only reads the first 10 columns. Columns contents exceeding 255 characters are truncated. The script function supplies the value " " if an attempt is made to access a non-existing column.
RETCODE	Return code of the job in converted format
RETCODE_STATE	Filter specification for the return code Allowed values: "Y" and "N" "Y" - A filter has been set for the return code "N" - The return code is not relevant for event triggering
SEND_JOB	Name of the job in which the received message was sent
SEND_JOB_NUMBER	JobVerarbeitung auf einem Zielsystem. Auch ein eigener Objekttyp in der Automation Engine. number of the job which the received message was sent
SEND_USER_PROFILE	Name of the user profile which sent the received message
SERVICE	Service
SMS_MANAGEMENT_CLASS SMS_DATA_CLASS SMS_STORAGE_CLASS	Name of the class
SOURCE	Source of the event
STATE	Status Allowed values: "*" "ERROR" "OK" "INACTIVE" "UNKNOWN" "UNREGISTERED"
STEP_NAME	Name of the job step
SYS_NAME	User-defined system name
SYSPLEX_NAME	SYSPLEX name
TIMESTAMP	Date and time of the console message
TYPE	Type of the event Allowed values: "I" - information "W" - warning "E" - error "S" - success audit "F" - failure audit
USER	User

Comments

The script elements GET_CONSOLE and GET_EVENT_INFO can be used to retrieve information about an occurred event. They have the same syntax.

With the script function GET_CONSOLE, message data can be retrieved when console events occur. This data consists of defined components of the console message, which can be specified with keyword. By default, this function returns the message text.

This script function can be used in the event type "Console". The console message can be read with this in BS2000 and in z/OS. In OS/400, this script function is used to receive information from a message queue. The message queue to be monitored can be specified in the INI file of the OS/400 agent.

GET_EVENT_INFO can be used to read information in the scripts of File System events. Especially z/OS provides several keywords.

Platform Specific Features

z/OS

The keywords MSG_DESCRIPTOR, MSG_LEVEL and MSG_MISC represent special features. They are 16-bit fields of which each individual bit has a specific meaning. Each individual bit can be queried with this script function. This can be done by giving the bit a value or a constant with Index. The value returned by this script function is "1" (bit is set) or "0" (bit is not set).

OS/400

With INSERT_COUNT as the keyword, you can establish the number of variable parts of a message in a OS/400 message. With INSERT as the keyword and by specifying the Index, a specific variable part of a message can be accessed. Without Index ,the function returns the first variable part of the message.

Examples

The function GET_CONSOLE is used to retrieve the TSN of the process which triggered the event.

:GET_CONSOLE(PROCESSID)

In the second example, first the number of the variable part of the message of a OS/400 message is determined. Then, a process loop runs in which all inserts are written in the activation report.

:SET &COUNT# = GET_CONSOLE("INSERT_COUNT")
:SET &IDX# = 1
:WHILE &COUNT# > 0
:   SET &INSERT# = GET_CONSOLE("INSERT", &IDX#)
:   SET &HELP# = FORMAT(&IDX#, "000")
:   PRINT "INSERT[&HELP#] = '&INSERT#'"
:   SET &IDX# = ADD(&IDX#, 1)
:   SET &COUNT# = SUB(&COUNT#, 1)
:ENDWHILE

The following lines are logged in the activation report:

20010110/235011.000 - U0020408 INSERT[001] = 'QPFRMON'
20010110/235011.000 - U0020408 INSERT[002] = 'QPGMR'
20010110/235011.000 - U0020408 INSERT[003] = '007982'
20010110/235011.000 - U0020408 INSERT[004] = '23:48:43'
20010110/235011.000 - U0020408 INSERT[005] = '10/01/01'
20010110/235011.000 - U0020408 INSERT[006] = '0'

In the third example, a component of the console message in z/OS is requested. Bit 03 of the keyword MSG_DESCRIPTOR is accessed. Bit 03 is given either as a value or a constant.

:SET &RET# = GET_CONSOLE("MSG_DESCRIPTOR", 3)

:SET &RET# = GET_CONSOLE("MSG_DESCRIPTOR", "EVENTUAL_ACTION")

The following example shows a script excerpt which retrieves the file name and reads the file content line by line.

:SET &FILE NAME# = GET_EVENT_INFO (FILENAME)
:SET &HND# = PREP_PROCESS_FILE ("MVSHOST", &FILE_NAME#)

The fifth example reads the values of an SQL query (for "Value 1") in a database event.

SQL results:

Last name	First name	Location
Smith	John	Seattle

The first name is retrieved as shown below:

:SET &First name# = GET_EVENT_INFO (RESULT1, 2)

The following line supplies the location:

:SET &Location# = GET_EVENT_INFO (RESULT1, 3)