Assign event stream to user task
Component: | BS2000 |
Functional area: | Job processing |
Domain: | CONSOLE-MANAGEMENT |
Privileges: | STD-PROCESSING |
Function
This command causes an event stream to be assigned to the user task from which it was issued. It has essentially three main functions:
Assigning an event stream to the user’s own task. This registers the user task with the event stream service (ESS) and causes an event stream task to start event stream logging in an event stream file (ESF). The components of the event stream are all asynchronous events addressed to the user task and the synchronous events defined when the command is issued. A nonprivileged user is allowed to assign a user event stream (TO=*USER-LOG). The user task is connected to a private user event stream, and events are logged in a private user event stream file (UESF). A user with the OPERATING privilege is able to assign a system event stream (TO=*SYSTEM-LOG), which involves the logging of all asynchronous system messages distributed via routing codes. In such cases the user task is connected to the central system event stream, and events are logged in the central system event stream file (SESF).
A user task can only ever be assigned one event stream (user or system event stream). If a user task with an event stream already assigned to it is assigned a new event stream, the assignment is changed to match the new specifications in the command. The assignment which applied before is canceled (implied TO=*DUMMY).
Canceling the assignment of an event stream to the user’s own task (ASSIGN-SYSEVENT TO=*DUMMY). The user task is deregistered from the ESS, and the events from the event stream are no longer logged in the ESF.
Modifying the assigned event stream. This primarily lets you redefine the set of synchronous messages being logged within an existing assignment (i.e. for your own active event stream).
Format
ASSIGN-SYSEVENT | ||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
TO = *USER-LOG(...) / *DUMMY / *CURRENT / *SYSTEM-LOG(...)
Specifies the logical medium to which the assignment is to relate, thereby defining the function of the command (start, stop or modify an event stream).
TO = *USER-LOG(...)
Assigns a user event stream to the user task. The associated events are logged in a UESF.
LOG-ID = *OWN-TSN / <alphanum-name 1..4>
Defines the name that is assigned to the event stream. The default name is the TSN of your own task.
OPEN-MODE = *CREATE / *OUTPUT / *EXTEND
Defines the open mode for event stream assignment. You can either create a new event stream or continue with an existing one.
OPEN-MODE = *CREATE
Creates and starts a new event stream. The UESF is created. If an event stream of the same name and type already exists, the command is rejected.
OPEN-MODE = *OUTPUT
Reassigns and overwrites an existing, closed event stream. If the event stream does not yet exist, a new one is created. The UESF is overwritten, or a new one is created. The event stream record is updated accordingly.
OPEN-MODE = *EXTEND
Reassigns and extends an existing, closed event stream. If the event stream does not exist, the command is rejected.
TO = *DUMMY
Cancels the currently applicable assignments of the event stream. Logging of the associated events in the UESF or the central SESF is terminated. As you can only refer to your own active event stream, there is no need to indicate a LOG-ID.
TO = *CURRENT
Modifies the properties of the currently applicable event stream assignment. As you can only refer to your own active event stream, there is no need to indicate a LOG-ID.
TO = *SYSTEM-LOG(...)
Reserved for users with the OPERATING privilege.
Assigns a system event stream to the user task. The associated events are logged in the central SESF.
LOG-ID = *OWN-TSN / <alphanum-name 1..4>
Defines the name that is assigned to the event stream. The default name is the TSN of your own task.
OPEN-MODE = *CREATE / *OUTPUT / *EXTEND
Defines the open mode for event stream assignment. You can either create a new event stream or continue with an existing one.
OPEN-MODE = *CREATE
Creates and starts a new event stream. If an event stream of the same name and type already exists, the command is rejected.
OPEN-MODE = *OUTPUT
Reassigns and overwrites an existing, closed event stream. If the event stream does not yet exist, a new one is created. The event stream record is updated accordingly.
OPEN-MODE = *EXTEND
Reassigns and extends an existing, closed event stream. If the event stream does not exist, the command is rejected.
ADD-SYNCH-EVENTS = *UNCHANGED-OR-STD / *NONE / *ALL / list-poss(3): *SYSOUT-MSG / *CMD / *STMT
Defines the logical set of event stream components that is to be logged in addition to the asynchronous messages addressed to the user task.
ADD-SYNCH-EVENTS = *UNCHANGED-OR-STD
Additional logging is determined by the type of assignment:
If you are assigning an event stream using TO=*USER-LOG or *SYSTEM-LOG, then ADD-SYNCH-EVENTS=*NONE applies. If you are modifying the assigned event stream using TO=*CURRENT, the current setting is retained unmodified. The operand is ignored for an assignment using TO=*DUMMY.
ADD-SYNCH-EVENTS = *NONE
Only asynchronous events addressed to the user task are to be logged.
ADD-SYNCH-EVENTS = *ALL
All message types are to be logged.
ADD-SYNCH-EVENTS = *SYSOUT-MSG
Messages sent to SYSOUT by command servers and user programs are to be logged in addition to asynchronous messages. Logging also extends to:
all system messages and unformatted WROUT output, but not to FHS masks or other formatted screen output (such as EDT masks)
all WRTRD output of the message system (MIP) which requires a response. A message requiring a response (query message) is always logged together with the response because the query and the response are logically related.
ADD-SYNCH-EVENTS = *CMD
Commands input from the user task which are executed using SDF are to be logged in addition to the asynchronous messages.
ADD-SYNCH-EVENTS = *STMT
Statements input from within a user program in the user task which are executed using SDF are to be logged in addition to the asynchronous messages.
CLOSE-MODE = *UNCHANGED-OR-STD / *DELETE-EVENTS / *KEEP-EVENTS
Governs whether the event stream is simply to be closed or is also to be deleted when the assignment is canceled. If the assignment is switched from one event stream to another, this operand only ever applies to the second event stream. The event stream that is closed when the assignment is switched keeps the setting it had beforehand.
CLOSE-MODE = *UNCHANGED-OR-STD
If you are assigning the event stream using LOG-ID, this operand value defaults to CLOSE-MODE=*DELETE-EVENTS. If you are canceling the assignment using TO=*DUMMY or modifying the assigned event stream using TO=*CURRENT, the setting defaults to *UNCHANGED, which means that the previous setting is retained.
CLOSE-MODE = *DELETE-EVENTS
Specifies that the event stream record and the logged events are to be deleted when the assignment is canceled. If a user task has been assigned a user event stream (TO=*USER-LOG), the associated UESF is deleted as well.
CLOSE-MODE = *KEEP-EVENTS
Specifies that the event stream record and the logged events are not to be deleted when the assignment is canceled. The SHOW-SYSEVENT-LOG command can still be used to display the logged events. If a user task has been assigned a user event stream (TO=*USER-LOG), the associated UESF is saved.
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | Command executed successfully | |
1 | 0 | NBR3103 | No need to execute command, no event stream assigned |
1 | CMD0202 | Syntax error | |
32 | NBR3199 | Internal error on command server | |
32 | NBR3111 | Error generating user event stream task (UEST) | |
32 | NBR3112 | System event stream task (SEST) not available | |
64 | CMD0216 | User does not have the necessary privilege | |
64 | NBR3012 | Initialization error in user event stream task (UEST) | |
64 | NBR3014 | Termination error in user event stream task (UEST) | |
64 | NBR3102 | Name of event stream not unique | |
64 | NBR3106 | Event stream already assigned, | |
64 | NBR3107 | Event stream file (ESF) locked | |
64 | NBR3108 | Event stream not available | |
64 | NBR3113 | Event stream not assigned owing to /SHUTDOWN |