[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP OpenVMS DCL Dictionary

Note that with this qualifier, all X authority file specifications resolve to a physical device (rather than a logical device) in order to remain available to other detached processes. If you specify a search list, and the file is not found, the X authority file specification resolves to the first directory in the search list.

Use /NOXAUTHORITY to clear the setting and return to the file referenced by the DECW$XAUTHORITY logical or the default file if the logical is not defined.

Examples

$ SHOW DISPLAY
  Device:     WSA1: [super]
  Node:       0
  Transport:  LOCAL
  Server:     0
  Screen:     0

$ SET DISPLAY/CREATE/NODE=ZEPHYR/EXECUTIVE_MODE
$ SHOW DISPLAY
  Device:     WSA2:  [exec]
  Node:       ZEPHYR
  Transport:  DECNET
  Server:     0
  Screen:     0
$ SPAWN/NOWAIT/INPUT=NL: RUN SYS$SYSTEM:DECW$CLOCK

$ SET DISPLAY/DELETE

$ SHOW DISPLAY
  Device:     WSA1:  [super]
  Node:       0
  Transport:  LOCAL
  Server:     0
  Screen:     0

In this example, you are logged in to your workstation (device WSA1:), here referred to as node 0. (0 is the standard shorthand notation for representing your node.) You want to run the DECwindows Clock on your workstation and display it on another workstation, ZEPHYR.
Assuming you are authorized to display applications on ZEPHYR, you redirect the application's output to ZEPHYR with the SET DISPLAY command. The device created on ZEPHYR is an executive-mode device. You enter the SHOW DISPLAY command to verify the location of the redirected display. You then run Clock. When you finish running Clock, you disable the redirected display by entering the SET DISPLAY/DELETE command. Finally, you enter the SHOW DISPLAY command to verify that any applications subsequently run on your node will also be displayed there.
Note that a new workstation display device, WSA2, is created when you enter the SET DISPLAY/CREATE command. When you cancel the redirected display with the SET DISPLAY/DELETE command, application output is once again displayed on the workstation display device referred to by WSA1.

$ SET DISPLAY/CREATE/NODE=FLOPSY RABBIT
$ SHOW DISPLAY RABBIT

 Device:    WSA2:  [super]
 Node:      FLOPSY
 Transport: DECNET
 Server:    0
 Screen:    0

$ RUN/DETACHED/OUTPUT=WSA2: SYS$SYSTEM:DECW$CLOCK

$ SET DISPLAY/CREATE/NODE=ZEPHYR ZNODE
$ SHOW DISPLAY ZNODE

 Device:    WSA3:  [super]
 Node:      ZEPHYR
 Transport: DECNET
 Server:    0
 Screen:    0

$ RUN/DETACHED/OUTPUT=WSA3: SYS$SYSTEM:DECW$CALENDAR

$ RUN SYS$SYSTEM:DECW$BOOKREADER
$ SHOW DISPLAY

 Device:    WSA1:  [super]
 Node:      0
 Transport: LOCAL
 Server:    0
 Screen:    0

In this example, you are logged in to your node (device WSA1:), and want to direct the output from applications to several workstation displays in the same session. By specifying different logical names in the SET DISPLAY command, you can redirect the output without changing the logical name definition for DECW$DISPLAY. This allows you to display the output from most applications on your default display but occasionally display output on another workstation. You can also continue to run and display applications on your node. In this example, Clock is displayed on node FLOPSY, Calendar is displayed on node ZEPHYR, and Bookreader is displayed on your workstation.
Note that to run your applications with the DCL command RUN/DETACHED, you must use the device name that equates to the logical display device name you specified in the SET DISPLAY command. Use the SHOW DISPLAY command to obtain this device name.

$ SET DISPLAY/CREATE/GENERATE=TRUSTED/XAUTHORITY=XAUTHORITY_TEMP/NODE=ZEPHYR
$ PIPE SHOW DISPLAY/EXTRACT | RSH FLOPSY "XAUTH NMERGE SYS$INPUT"
$ SET HOST FLOPSY
$ SET DISPLAY/NODE=ZEPHYR
$ RUN SYS$SYSTEM:DECW$CLOCK

In this example, you are logged into your workstation (WSA1:) and want to run the DECwindows Clock application on a remote node (FLOPSY) and display it on another workstation (ZEPHYR). Both systems are using Magic Cookie authorization to control access to the X display server.
Assuming you are already authorized to connect to the server on node ZEPHYR, you create a display device that connects to ZEPHYR and generates a new authorization key. This key grants trusted connections to the server on ZEPHYR within 60 seconds of key generation. To restrict trusted access to the server, the key is stored in a new X authority file, XAUTHORITY_TEMP.DECW$XAUTH.
The authorization key is then extracted and copied to FLOPSY, and merged with other entries in your X authority file on that system. You then set host to node FLOPSY and set display to node ZEPHYR. When you run the clock application from FLOPSY, it connects to the server on ZEPHYR and is allowed access as specified by the generated authorization key.

$ SET DISPLAY/CREATE/VALUE=(NAME=DECW$SESSION_MANAGER,SET="tcpip/zephyr:9510")
$ SHOW DISPLAY/SYMBOLS/ALL
    Device:    WSA23:  [super]
    Node:      0
    Transport: DECNET
    Server:    0
    Screen:    0
  User-defined values:
    "DECW$SESSION_MANAGER" = "tcpip/zephyr:9510"
$ SHOW SYMBOL DECW$DISPLAY__DECW$SESSION_MANAGER
  DECW$DISPLAY__DECW$SESSION_MANAGER == "tcpip/zephyr:9510"
$ SET DISPLAY UNTRUSTED/CREATE/XAUTHORITY=TEMP/GENERATE-
_$ /VALUE=(NAME=DECW$SESSION_MANAGER,-)
_$ SET="'DECW$DISPLAY__DECW$SESSION_MANAGER'")

In this example, you create a display device, and set the DECW$SESSION_MANAGER property to the network address of a session manager on remote node ZEPHYR using port number 9510. The SHOW DISPLAY/SYMBOLS command then defines a DCL symbol for the port value. The symbol is then used to set the port value for a new display device.

$ SET DISPLAY/CREATE/PROXY=GATEWY/NODE=hubbub.company.com-
_$ /PMTRANSPORT=DECNET/NOLBXAUTHENTICATE/TRANSPORT=TCPIP
$ SHOW DISPLAY
    Device:    WSA23:  [super]
    Node:      HUBBUB.COMPANY.COM
    Transport: TCPIP
    Server:    0
    Screen:    0
  Connection will use:
    LBX proxy on node:  gatewy.company.com
    Transport to proxy: TCPIP
    Server number:      63
$ RUN SYS$SYSTEM:DECW$CLOCK

In this example, you are logged into a local workstation (FLOPSY) and want to connect to an external host (hubbub.company.com), which is outside of your company's firewall. You use the proxy manager on a gateway host (GATEWY) to start the LBX proxy server, connect to the external host, and display the DECwindows Clock application.
Note that DECnet is used within the local area network (LAN) to communicate to the proxy manager, and TCP/IP is used by the proxy server to communicate to the X display server on the external host. When using a managed proxy server, the proxy server chooses the transport for the client-to-proxy server connection.

SET ENTRY

Changes the current status or attributes of a job not currently executing in a queue.
Requires delete (D) access to the job or manage (M) access to the queue.

Format

SET ENTRY entry-number[,...]

Parameter

entry-number[,...]
Specifies the entry number of the job you want to change. If you specify more than one entry, separate the entry numbers with commas (,).
The system assigns a unique entry number to each queued print or batch job in the system. By default, the PRINT and SUBMIT commands display the entry number when they successfully queue a job for processing. These commands also create or update the local symbol $ENTRY to reflect the entry number of the most recently queued job. To find a job's entry number, enter the SHOW ENTRY or the SHOW QUEUE command.

Description

The SET ENTRY command allows you to change the status or attributes of one or more jobs, as long as the jobs are not executing currently. You cannot affect individual files within a multifile job with the SET ENTRY command.
The qualifiers enable you to specify different attributes or delete attributes. Some qualifiers apply to both batch and print jobs. Others are restricted to either batch jobs or print jobs. The defaults for all the SET ENTRY qualifiers are the attributes and status that the job has before you enter the SET ENTRY command.
This command requires delete (D) access to the job, manage (M) access to the queue, or OPER (operator) privilege.

Qualifiers

/AFTER=time

/NOAFTER
Requests that the specified job be held until after a specific time. If the specified time has already passed, the job is scheduled for processing.
You can specify either absolute time or a combination of absolute and delta times. For complete information on specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).

Note
Releasing or rescheduling a job before its submission time is not supported for security reasons. Therefore, if you set the system time to a future time and submit a job on a node where the queue manager is running, you cannot release or reschedule that job back to the present time if you reset the system time.
For example, you can set the system time to a future time of January 1, 2020 and submit a job to run on January 9, 2020; however, if you set the system time back to the present time and try to release the job to the present time, the job will be released to January 1, 2020.
This situation impacts the following qualifiers: /AFTER, /NOHOLD, and /RELEASE.

To specify /AFTER for a job on hold, you must also specify /NOHOLD in order to cause the job to be held only until the specified time. Jobs can be released before the specified time by using the /NOAFTER or /RELEASE qualifier with the SET ENTRY command.
/BURST

/NOBURST
Controls whether two file flag pages with a burst bar between them are printed preceding each file in a job.
Use the /[NO]BURST qualifier to override the /DEFAULT qualifier options that have been set for the output queue you are using. The /[NO]BURST qualifier does not override the /SEPARATE qualifier options set for the queue.
When you specify the /BURST qualifier for a file, the /[NO]FLAG qualifier does not add or subtract a flag page from the two flag pages that are printed preceding a file.
/CHARACTERISTICS=(characteristic[,...])

/NOCHARACTERISTICS
Specifies the name or number of one or more characteristics to be associated with the job. Characteristics can refer to such things as color of ink. If you specify only one characteristic, you can omit the parentheses.
A characteristic's number must range from 0 to 127. To see which characteristics have been defined for your system, use the SHOW QUEUE/CHARACTERISTICS command. To see which characteristics are associated with a particular queue, use the SHOW QUEUE/FULL command.
A print job can be processed on an execution queue if none, some, or all of the characteristics associated with the queue also are associated with the job. That is, the job's characteristics must be a subset of the queue's characteristics. However, if any of the characteristics associated with the job are not associated with the queue, the job remains pending until one or more of the following occurs:

The characteristics specified with the queue are changed to make the job's characteristics a subset of the queue's characteristics (using, for example, the SET QUEUE/CHARACTERISTICS command).
The characteristics specified with the job are changed to make the job's characteristics a subset of the queue's characteristics (using, for example, the SET ENTRY/CHARACTERISTICS command).
The job is moved to a queue on which all the job's characteristics have been specified (using, for example, the SET ENTRY/REQUEUE command).
The job is deleted (using, for example, the DELETE/ENTRY command).

/CLI=filename
Specifies the name of a command language interpreter (CLI) to use in processing the batch job. The file name specifies that the CLI be SYS$SYSTEM:filename.EXE. If you do not specify the /CLI qualifier, the job is run by the CLI specified in the user authorization file (UAF), or whatever CLI was specified when the job was originally submitted to the queue.
/COPIES=n
Specifies the number of copies to print. The value of n can be any number from 1 to 255. When you use the /COPIES qualifier with the SET ENTRY command, the number of copies can apply only to the entire print job. You cannot use this qualifier to specify different numbers of copies for individual files within a multifile job.
/CPUTIME=time
Specifies a CPU time limit for the batch job. You can specify the time parameter as delta time, the value 0, INFINITE, or NONE. If the queue on which the job executes has a defined CPUMAXIMUM value, the smaller of the specified job and queue values is used. If the queue on which the job executes does not have a specified maximum CPU time limit, the smaller of the SUBMIT command and user authorization file (UAF) values is used. If the queue on which the job executes does not have a specified maximum CPU time limit and the UAF has a specified CPU time limit of NONE, either the value 0 or the keyword INFINITE allows unlimited CPU time. If you specify NONE, the specified queue or UAF value is used. CPU time values must be greater than or equal to the number specified by the system parameter PQL_MCPULM.
For more information on specifying CPU time limits, see the CPU Time Limit Specifications and Actions table for the INITIALIZE/QUEUE command. For information on specifying time values, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).
/FEED

/NOFEED
Controls whether form feeds are inserted into the print job when the printer reaches the bottom margin of the form in use. You can suppress this automatic form feed (without affecting any of the other carriage control functions that are in place) by using the /NOFEED qualifier.
When you use the /FEED qualifier with the SET ENTRY command, the qualifier applies to all files in the print job. You cannot use this qualifier to specify form feeds for individual files within a multifile job.
/FLAG

/NOFLAG
Controls whether a flag page is printed preceding each file in a print job. The flag page contains the name of the user submitting the job, the job entry number, and other information about the file being printed.
Use the /[NO]FLAG qualifier to override the installation-defined defaults that have been set for the output queue you are using or to override the qualifier specified in the PRINT command that queued the job.
/FORM=form
Specifies the name or number of the form to be associated with the print job. If you omit the /FORM qualifier, the default form for the execution queue is associated with the job.
Forms have attributes such as print image width and length or paper stock, which the print symbiont associates with a job when the job is processed. To see which forms have been defined for your system, use the SHOW QUEUE/FORM command. To find out which form is mounted currently on a particular queue and which form is specified as that queue's default form, use the SHOW QUEUE/FULL command.
The stock of the form associated with the job must match the stock of the form mounted on the execution queue on which you want the job to be processed. If the stocks do not match, the job remains pending until one or more of the following occurs:

A form with the same stock as the job's form is mounted on the queue (using, for example, the SET QUEUE/FORM_MOUNTED command).
A form with the same stock as the queue's mounted form is specified with the job (using, for example, the SET ENTRY/FORM command).
The job is moved to a queue on which the stock of the mounted form matches the stock of the job's form (using, for example, the SET ENTRY/REQUEUE command).
The job is deleted (using, for example, the DELETE/ENTRY command).

/HEADER

/NOHEADER
Controls whether a heading line is printed at the top of each output page in a print job.
/HOLD

/NOHOLD
Controls whether the job is to be made available for processing or held for processing later. If you specify the /HOLD qualifier, the job is not released for processing until you enter SET ENTRY/NOHOLD or SET ENTRY/RELEASE.
You can use the /NOHOLD qualifier to release jobs that have been held for the following reasons:

A job was submitted with the /HOLD qualifier.
A completed job is being retained in a queue.
A user-written symbiont has refused a job.

Note
Releasing or rescheduling a job before its submission time is not supported for security reasons. Therefore, if you set the system time to a future time and submit a job on a node where the queue manager is running, you cannot release or reschedule that job back to the present time if you reset the system time.
For example, you can set the system time to a future time of January 1, 2020 and submit a job to run on January 9, 2020; however, if you set the system time back to the present time and try to release the job to the present time, the job will be released to January 1, 2020.
This situation impacts the following qualifiers: /AFTER, /NOHOLD, and /RELEASE.

/JOB_COUNT=n
Requests that an entire print job be printed n times, where n is a decimal integer from 1 to 255. This qualifier overrides the /JOB_COUNT qualifier with the PRINT command.
/KEEP

/NOKEEP
Controls whether the batch job log file is deleted after it is printed.
/LOG_FILE[=filespec]

/NOLOG_FILE
Creates a log file with the specified file specification. You can specify a different device name, as long as the process executing the batch job has access to the device on which the log file will reside. Logical names in the file specification are translated in the context of the process that executes the SET ENTRY command.
If you omit the /LOG_FILE qualifier and specify the /NAME qualifier, the log file is written to a file having the same file name as that specified by the /NAME qualifier; the file type is .LOG. When you omit the /LOG_FILE qualifier, the job-name value used with the /NAME qualifier must be a valid file name.
/LOWERCASE

/NOLOWERCASE
Indicates whether the print job must be printed on a printer that can print both uppercase and lowercase letters. The /NOLOWERCASE qualifier means that files can be printed on printers that print only uppercase letters. If all available printers can print both uppercase and lowercase letters, you do not need to specify the /LOWERCASE qualifier.
/NAME=job-name
Names the job. The job name must be 1 to 39 alphanumeric characters. The SHOW ENTRY and SHOW QUEUE commands display the job name. For batch jobs, the job name is also used for the batch job log file. For print jobs, the job name is also used on the flag page of the printed output.
The default job name is the name of the first file in the job.
/NOCHECKPOINT
For a batch job, erases the value established by the most recently executed SET RESTART_VALUE command. For a print job, clears the stored checkpoint so that the job will restart from the beginning.
/NODELETE
Cancels file deletion for a job that was submitted with the /DELETE qualifier. If you did not specify the /DELETE qualifier when the job was originally submitted to the queue, you cannot use the SET ENTRY command to establish file deletion at a later time. You cannot use the /NODELETE qualifier to cancel deletion of individual files in a multifile job.
/NOTE=string
Specifies a message of up to 255 characters to appear on the flag page of the print job. Enclose messages containing lowercase letters, blanks, or other nonalphanumeric characters (including spaces) in quotation marks (" ").
/NOTIFY

/NONOTIFY
Controls whether a message notifies you when your job has been completed or aborted. Notification is sent to any terminal session on the same OpenVMS Cluster system to which you are logged in.
/OPERATOR=string
Specifies a message string of up to 255 characters to be sent to the operator just before the print job begins to print. Enclose the message in quotation marks (" ") if it contains spaces, special characters, or lowercase characters.
/PAGES=([lowlim,]uplim)
Specifies the number of pages to print for the specified job. You can use the /PAGES qualifier to print portions of long files. By default, all pages of the file are printed. When you use the /PAGES qualifier with the SET ENTRY command, the qualifier can apply only to an entire job. You cannot use this qualifier to specify different numbers of pages to be printed for individual files within a multifile job.
The lowlim specifier refers to the first page of the file that you want to print. If you omit the lowlim specifier, the printing starts on the first page of the file.
The uplim specifier refers to the last page of the file that you want to print. When you want to print to the end of the file but do not know how many pages are in the file, use quotation marks (" ") as the uplim specifier.
You can omit the parentheses when you specify only a value for the uplim specifier. For example, /PAGES=10 prints the first 10 pages of the file; /PAGES=(5,10) prints pages 5 to 10; /PAGES=(5,"") starts printing at page 5 and continues until the end of the file is reached.
/PARAMETERS=(parameter[,...])
Specifies from one to eight optional parameters to be passed to the job. Each parameter can have as many as 255 characters. If you specify only one parameter, you can omit the parentheses. To specify a parameter that contains any special characters or delimiters, enclose the parameter in quotation marks.
For batch jobs, the parameters define values to be equated to the symbols named P1 to P8 in each command procedure in the job. The symbols are local to the specified command procedures.
/PASSALL

/NOPASSALL
Specifies whether the symbiont bypasses all formatting of the print job and sends the output QIO to the driver with format suppressed. All qualifiers affecting formatting, as well as the /HEADER, /PAGES, and /PAGE_SETUP qualifiers, are ignored.
When you use the /PASSALL qualifier with the SET ENTRY command, the qualifier applies to the entire job. You cannot use this qualifier to specify PASSALL mode for individual files within a multifile job.
/PRINTER[=queue-name]

/NOPRINTER
Queues the batch job log file for printing when the job is completed. The default output queue for the log file is SYS$PRINT. The /PRINTER qualifier allows you to specify an output queue. The /NOPRINTER qualifier assumes the /KEEP qualifier.
/PRIORITY=n
Requires OPER (operator) or ALTPRI (alter priority) privilege to raise the priority above the value of the queue's maximum scheduling priority.
Specifies the job-scheduling priority of the job. The value of n is an integer in the range of 0 to 255, where 0 is the lowest priority and 255 is the highest.
The default value for the /PRIORITY qualifier is the value of the system parameter DEFQUEPRI. No privilege is needed to set the priority lower than the queue's maximum scheduling priority.
/RAD=n (Alpha only)
Specifies the RAD number on which the submitted batch job is to execute.
When a job is submitted to a batch queue that does not have a RAD setting, the job will execute using the RAD specified. If the batch queue has a RAD setting, the job will execute using the RAD specified on the queue.
Supported only on AlphaServer GS series systems.
/RELEASE
You can use the /RELEASE qualifier to release jobs that have been held for the following reasons:

A job was submitted with the /AFTER qualifier.
A job was submitted with the /HOLD qualifier.
A completed job is being retained in a queue.
A user-written symbiont has refused a job.

Note
Releasing or rescheduling a job before its submission time is not supported for security reasons. Therefore, if you set the system time to a future time and submit a job on a node where the queue manager is running, you cannot release or reschedule that job back to the present time if you reset the system time.
For example, you can set the system time to a future time of January 1, 2020 and submit a job to run on January 9, 2020; however, if you set the system time back to the present time and try to release the job to the present time, the job will be released to January 1, 2020.
This situation impacts the following qualifiers: /AFTER, /NOHOLD, and /RELEASE.

/REQUEUE=queue-name[:]
Requests that the job be moved from the original queue to the specified queue.
/RESTART

/NORESTART
Specifies whether a batch or print job is restarted after a system failure or a STOP/QUEUE/REQUEUE command.
/RETAIN=option
Specifies the circumstances under which you want your jobs to be retained in a queue. When a job is retained in the queue, you can issue the SHOW QUEUE command after the job completes to see the status of the job. Without job retention, no record of a job is left in a queue after a job completes.
Use the following options to specify job retention:

ALWAYS---Holds the job in the queue regardless of the job's completion status.
DEFAULT---Holds the job in the queue as specified by the queue's retention policy.
ERROR---Holds the job in the queue only if the job completes unsuccessfully.
UNTIL=time-value----Holds the job in the queue for the specified length of time, regardless of the job's completion status.

Note
You cannot specify a /NORETAIN qualifier with the SET ENTRY command (as system managers can with the commands INITIALIZE/QUEUE, START/QUEUE, and SET QUEUE); however, you can specify /RETAIN=DEFAULT with the SET ENTRY command. The default option holds the job in the queue as specified by the queue's retention policy. If the system manager has not specified retention for the queue, the job is not retained.

How Job Retention Is Determined

Although you can specify job retention options for your own jobs, the job retention option you specify may be overridden by the job retention option of the queue on which your job executed. If you submit or print a job to a generic queue, the generic queue's job retention setting may also override the job retention option you specify. This section describes how job retention is determined.
An execution queue's job retention setting takes precedence over a generic queue's job retention setting; however, if the job's completion status does not match the job retention setting (if any) on the execution queue, then the generic queue's job retention setting attempts to control job retention. If the job's completion status does not match the job retention setting (if any) on the generic queue, then the user-specified job retention setting is used. Jobs submitted directly to execution queues are not affected by job retention settings on generic queues.

Previous Next Contents Index