# end command (TCL commands) The end command terminates a process on another port, or the current port if a port number is not specified. ## Syntax ``` end {port.number user-ID} ``` ## Description The end command stops processing at the previous level and returns to the preceding level TCL prompt. However, if there is an active list at the current level, then list is cleared, and control is returned to the previous level. The end command can also be used to stop a TCL command that was sent to another line by the tcl command, or to terminate a *phantom* job. The end command clears an active list and requires a sys2 privilege level. Note: - If the port number and user-ID are not specified, the end command stops the process on the current line. - If the specified process is in the debugger, the end command fails with an error message. Warning: This can have a two-fold affect under certain circumstances. For instance, if a process is in effect at the first level, and the operator pushes a level, performs a select or some other *list-producing* command, then decides to abandon the list, the end command abandons the list and ends the process at level one. The way around this is by pressing ENTER at the *second level* prompt character, which automatically releases the active list and returns to the previous level. Using the end command on another port should be used by a system administrator only when the status of the PIB and potential problems that could arise have been assessed. The end command can generate file inconsistency errors in some rare instances. ## Example(s) Ends the process at the current level. ``` end ``` Stops the process executing on line 16, under the user-ID, dm. ``` end 16 dm ``` This kills an active list. ``` select dict entity [404] 276 items selected out of 276 items. end ``` The end command logs details of the operation to the dm,errors,end file. This file is created by the end.sub subroutine. If an end command has never been run, this file may not yet exist. Information about the state of the target is logged before and after the end command is run unless the target line is the line issuing the command. In such a case, only the state before is logged. As with many files, it should be monitored to ensure it is properly sized and to remove any unwanted entries. The end-createadis command can be used to populate dict dm,errors, with attribute-defining items for use with the log entries created by end. Each ADI begins with the `end.` prefix. ## Developer’s programming API The end command uses a program-friendly API in the form of a BASIC subroutine. This allows calling the subroutine instead of using an execute statement with a capturing clause. The subroutine is dm,bp, end.sub and has the following API. ``` sub end.sub(command, outCapture, outReturn, outNoLog, outCancel, outBeforeResult, outAfterResult) ``` **Input** | command | The first four characters must be "end " (end followed by a space). This avoids situations where it is accidentally called with a shutdown (y or similar. | | --- | --- | **Output** | outCapture | The capturing results of the execute ":end ..." capturing cap and returning ret. | | --- | --- | | outReturn | The returning results of the execute ":end ..." capturing cap and returning ret. | | outNoLog: | 1 = the operation could not be logged0 = the operation was logged. | | outCancel | Value returned by the user-defined triggerBefore(); that is, was the end canceled? | | outBeforeResult | Value returned by the user-defined triggerBefore(). | | outAfterResult | Value returned by the user-defined triggerAfter(). | The end command also supports two triggers (hooks) that allow inserting user-defined code into its execution stack. One trigger is called before ending the target and, in addition to whatever the user-defined code does, supports the ability to cancel the end command. The other trigger is called after ending the target. To tie into the execution stack, create the `config.end` item in the dict dm,errors, file. Attribute one is the subroutine to call before ending the target. Attribute two is the subroutine to call after ending the target. In the example below, the names mybefore.end and myafter.end are used. ``` config.end 001 dm,bp, mybefore.end 002 dm,bp, myafter.end ``` The triggers must have the following parameters (note that the before trigger has three input parameters and two output parameters): ``` command, targetLine, targetUser, outCancel, outBeforeResult ``` **Input** | command | The command as entered from TCL after being passed through trim(). | | --- | --- | | targetLine | The line number (target) of the end command. This is not validated and is simply whatever appears as the second word in the command argument. | | targetUser | The user-id (target) of the end command. This is not validated and is simply whatever appears as the third word in the command argument. | **Output** | outCancel | If set to 1, the end operation will be canceled. All attribute marks will be converted to value marks to ensure the content is restricted to a single attribute in the log. | | --- | --- | | outBeforeResult | Any user-defined output to add to the dm,errors,end log entry. All attribute marks will be converted to value marks to ensure the content is restricted to a single attribute in the log. | The after trigger has five input parameters and one output parameter: ``` command, targetLine, targetUser, cap, ret, outAfterResult ``` **Input** | command | The command as entered from TCL after being passed through trim(). | | --- | --- | | targetLine | The line number (target) of the end command. This is not validated and is simply whatever appears as the second word in the command argument. | | targetUser | The user-id (target) of the end command. This is not validated and is simply whatever appears as the third word in the command argument. | | cap | The results in the capturing clause variable from executing the end command. | | ret | The results in the returning clause variable from executing the end command. | **Output** | outAfterResult | Any user-defined output to add to the dm,errors,end log entry. All attribute marks will be converted to value marks to ensure the content is restricted to a single attribute in the log. | | --- | --- | Example of the before end trigger ``` mybefore.end sub mybefore.end(command, targetLine, targetUser, outCancel, outBeforeResult) crt "You are now in my realm." crt "command = '" : command : "'" crt "targetLine = '" : targetLine : "'" crt "targetUser = '" : targetUser : "'" prompt "" crt "Cancel ": in k if char(k)="y" then outBeforeResult = "Cancelling. You are not authorized to end this process." outCancel = 1 end else outBeforeResult = "Continuing. You have been authorized to end this process." end return ``` Example of the after end trigger ``` myafter.end sub myafter.end(command, targetLine, targetUser, cap, ret, outAfterResult) crt "You are leaving my realm." crt "command = '" : command : "'" crt "targetLine = '" : targetLine : "'" crt "targetUser = '" : targetUser : "'" crt "cap = '" : cap : "'" crt "ret = '" : ret : "'" outAfterResult = "You are free to go about your business." return ``` ## See also - [Active list](https://d3codex.com/definitions/active-list/) - [end command (Background/Phantom process commands)](https://d3codex.com/backgroundphantomprocess/end-command-background-phantom-process-commands/) - [Level pushing](https://d3codex.com/tcl/level-pushing/) - [list-jobs macro](https://d3codex.com/tcl/list-jobs-macro/) - [logoff command](https://d3codex.com/tcl/logoff-command/) - [logon command](https://d3codex.com/tcl/logon-command/) - [off command (TCL commands)](https://d3codex.com/tcl/off-command-tcl-commands/) - [Background/Phantom process overview](https://d3codex.com/backgroundphantomprocess/background-phantom-process-overview/) - [Port number](https://d3codex.com/definitions/port-number/) - [Secondary list](https://d3codex.com/definitions/secondary-list/) - [nselect command](https://d3codex.com/access/nselect-command/) - [sselect command](https://d3codex.com/access/sselect-command/) - [startsched command](https://d3codex.com/backgroundphantomprocess/startsched-command/) - [stopsched command](https://d3codex.com/tcl/stopsched-command/) - [tcl command](https://d3codex.com/tcl/tcl-command/) - [tcls command](https://d3codex.com/tcl/tcls-command/) - [z command (Background/Phantom process commands)](https://d3codex.com/backgroundphantomprocess/z-command-background-phantom-process-commands/) --- Source: https://d3codex.com/tcl/end-command-tcl-commands/ - part of the D3Codex reference.